[LarsLaskowski]

Pull Request

📖 Description

openHAB writes log timestamps without a zone offset, in the timezone configured in its Regional Settings. The parser interpreted them in the timezone of the viewer process, so on a host running on UTC with openHAB set to e.g. America/New_York, every timestamp in the UI was shifted by the zone difference (4 hours in the reported case).

This is a feature/fix with no breaking change:

• New optional setting LOG_TIMEZONE (IANA name). When set, LogLineParser converts timestamps from that zone to UTC via Intl.DateTimeFormat, independent of the process timezone. No new dependency.
  • DST edge cases: an ambiguous fall-back wall time resolves to the earlier instant; a non-existent spring-forward wall time is shifted forward.
  • The resolved offset is cached per wall-clock minute, so the zoned path is as fast as the default path (the uncached Intl conversion was ~7x slower).
• Unset keeps the previous behavior (process timezone). An unknown zone name logs a warning and falls back instead of failing startup; the name is normalized to its canonical spelling.
• The effective timezone is logged on startup (Reading log timestamps as …) to make offsets easy to diagnose from the journal.
• Docs:
  • README: prebuilt release packages are now the recommended installation path (Node.js 22+ only, no npm, no build), new Timezone of log timestamps section, and LOG_TIMEZONE in the configuration table and the env-file example.
  • ARCHITECTURE: replaces the "not configurable today" note with the new behavior.
  • systemd unit: commented-out LOG_TIMEZONE example.

🎫 Issues

Closes #195

👩‍💻 Reviewer Notes

• Focus: createZonedConverter() in src/server/logLineParser.ts (candidate selection around DST transitions and the per-minute cache).
• Smoke test: start the built server with TZ=UTC LOG_TIMEZONE=America/New_York against a log containing 2026-10-20 14:22:24.123 [INFO ] [a.b] - hello; /api/bootstrap returns 2026-10-20T18:22:24.123Z, and the UI shows 14:22 in a New York browser. This was verified locally.
• Users who already work around the issue with TZ=... are unaffected.

📑 Test Plan

• src/server/logLineParser.test.ts: new LogLineParser timezone handling suite covering the default process-local behavior, the issue Timestamp in LOG different that OS or wall clock time. #195 regression (EDT), standard time and zones east of UTC (Berlin, Kolkata, UTC), ambiguous fall-back times (New York, Berlin), the spring-forward gap, crossing a DST change within one parser (cache refresh), and continuation lines inheriting the zoned timestamp.
• src/server/config.test.ts: LOG_TIMEZONE default, valid value with spelling normalization, unknown zone fallback, whitespace-only value.
• src/server/routes.test.ts: config factory updated for the new field.
• The full suite passes with the process running in UTC, America/New_York, and Europe/Berlin.

✅ Checklist

General

• I have added unit tests for my changes, per UNIT_TESTS.md.
• I have run npm test and npm run typecheck locally and they pass.
• I have updated the project documentation (README, ARCHITECTURE, etc.) to reflect my changes, where applicable.
• I have read the CONTRIBUTING documentation and followed the project's code style and conventions.

Server-specific (src/server)

• I have added or updated a module in src/server (tailer, parser, buffer, routes, SSE hub, config, etc.).
• I have kept src/server/types.ts in sync with src/client/state.ts for any shared payload change (see ARCHITECTURE.md).
• I have preserved existing server-side bounds and defaults (buffer/SSE limits, poll interval clamps) unless the change explicitly targets them.

⏭ Next Steps

None.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
98.4% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud