loxone-datamanager: Instructions file for Claude Code

CLAUDE.md — Loxone DataManager

Electron desktop app (100% TypeScript) to view and edit Loxone Miniserver statistics: browse /stats via FTP/FTPS, chart/edit the binary monthly files, upload them back. Heavily inspired by LoxStatEdit (Windows/.NET). User-facing docs live in README.md; this file is for working on the code.

Commands (pnpm only — packageManager is pinned)

pnpm install          # pnpm 10: build scripts allowlisted via pnpm.onlyBuiltDependencies
pnpm run dev          # Electron + Vue with HMR
pnpm test             # vitest: parser round-trip, validation, formula, FTP date parsing
pnpm run build        # typecheck (node + web) + electron-vite build
pnpm run lint         # eslint + prettier rules
pnpm run build:mac    # package .dmg (build:win / build:linux)

Release: push a v* tag → .github/workflows/release.yml builds macOS universal .dmg + Windows NSIS setup.exe (unsigned) and drafts a GitHub Release.

Architecture

• src/main/ — Node/Electron main process. ALL FTP + file I/O lives here.
  • ftp.ts — one basic-ftp Client in a module singleton; every op serialized through a promise queue (run()) with one auto-reconnect retry; TLS auto-detect = try FTPS (secure: true, rejectUnauthorized: false — Miniserver certs are self-signed) then fall back to plain. LIST dates have no year → parseListDate heuristic (assume this year unless future).
  • statfile.ts — binary parser/serializer, pure TS, no Electron imports (unit-testable). See "Binary format" below.
  • cache.ts — per-host download cache in userData/stats-cache/<host>/. cachePath() validates names against STAT_FILENAME_RE (path-traversal guard).
  • store.ts — saved connections: plain JSON in userData + passwords encrypted with Electron safeStorage (no keychain → password simply not stored).
  • stats-service.ts — shared session logic for IPC and MCP so they can't diverge: CodedError/toApiError, the parsedFiles Map (serialization re-emits the original header bytes verbatim), saveRecords, buildCsv, MCP-side dirty tracking.
  • ipc.ts — all handlers, thin over stats-service. Every response is IpcResult<T> = {ok,data}|{ok,error} with typed ApiError.code (e.g. FTP_REFUSED triggers the "enable FTP" hint in the UI).
  • mcp.ts + mcp-tools.ts — embedded MCP server (@modelcontextprotocol/sdk v1, stateless Streamable HTTP: fresh McpServer + transport per POST) on http://127.0.0.1:<port>/mcp, default port 12009. Bearer-token auth (token generated in Settings, safeStorage-encrypted in store.ts, plain: prefix fallback); 20 tools + fix-statistics prompt share ftp/cache/stats-service with the UI. Edits are in-memory until save_stat_file; mcp:activity events tell the renderer to refresh (EditorView shows a reload banner — last-save-wins, no merging). Lifecycle: start on app ready if enabled, mcp:configure IPC restarts, EADDRINUSE lands in McpState.error.
  • updates.ts — release-notification only, no Electron imports (takes the current version as an argument, so it unit-tests). One fetch of GitHub's /releases/latest per launch; every failure (offline, 403 rate-limit, no published release) resolves as latest: null — a failed check must never surface as an app error. See "Auto-update" below for why there's no installer.
• src/preload/index.ts — contextBridge exposing window.api, typed by the single contract interface in src/shared/api.ts (preload implements it, renderer consumes it — extend the interface first when adding IPC).
• src/shared/ — types + time.ts (Loxone epoch helpers, multi-format timestamp parsing) + formula.ts (hand-rolled CSP-safe parser) + records.ts (pure record transforms: dominantInterval, fillGaps, summarizeRecords, statusOf, isCurrentMonth — used by the editor store AND the MCP tools; put new record logic here, not in a Pinia action).
• src/renderer/src/ — Vue 3 + Pinia + PrimeVue 4 + uPlot + vue-i18n. Views: Connection → Browser (file list w/ sync status) → Editor (chart + virtualized grid + problems panel), plus Settings (Cmd/Ctrl+, or gear icon). Router guard: everything except /connect and /settings needs a connection.
• i18n: en + de catalogs in renderer/src/locales/ (de.ts is typed typeof en so missing keys fail typecheck). ALL user-facing strings go through t(); error codes map to errors.* keys via errorText() in i18n.ts; validation problems translate by rule code in ProblemsPanel. Main-process messages stay English (fallback only).
• Prefs (renderer/src/prefs.ts, localStorage): date format (default DD.MM.YYYY) + time format (default 24h for every language — never let a locale silently switch to AM/PM). Editor-grid timestamps always render 24h so they stay parseable; displayToLox accepts all three date formats by separator. Theme lives in renderer/src/theme.ts (.app-dark class = PrimeVue darkModeSelector; chart palette watches isDark).