logging.h

#pragma once
#include <QString>

// Local log file.
//
// The app already emits the messages that matter — clickinjector.cpp reports
// which pointer-tracking backend it settled on ("evdev motion tracking active"
// vs "DISABLED — no readable devices"), which is the single most useful fact
// when dwell-clicking "stops working when the pointer leaves the toolbar" (see
// §2).  What was missing is anywhere for them to go: with no
// qInstallMessageHandler they land on stderr, which a GUI launch has no console
// for on Windows and buries in the unified log on macOS.  So the user reporting
// the bug has no way to get at the one line that explains it.
//
// This installs a handler that appends those same messages to a size-capped file
// under the app data directory, and still forwards every message to Qt's default
// handler so a developer running from a terminal sees no change.
//
// Deliberate boundaries — this is a local troubleshooting aid, not telemetry:
//
//   * The file is never uploaded or read by the usage reporter (§6).  The only
//     way it leaves the machine is the user copying it themselves.
//   * TrackClick does not capture keystrokes, and that holds here: custom-hotkey
//     *key sequences* are configuration and may appear, but nothing logs what the
//     user types into other applications.
//   * Bounded on disk by construction (see k_maxBytes) — two files, ~1 MB total,
//     no unbounded growth on a machine left running for months.
//
// The on/off switch is stored in its own QSettings key rather than in
// AppSettings, which keeps it out of profiles and out of settings export/import
// for the same reason the usage-reporting opt-out is excluded (§10): a config
// file passed between machines must not silently start or stop writing logs.

namespace logging {

// Install the message handler and open the log file.  Call once, from main(),
// after QApplication is constructed (the app/organisation name determines the
// path) and before anything that might log.  Honours the persisted on/off state,
// which is **off** until the user turns it on in Settings ▸ Diagnostics.
void install();

bool isEnabled();
// Persists immediately.  Turning logging off closes the file and stops all
// writes; the existing file is left on disk for the user to inspect or clear.
void setEnabled(bool on);

// Absolute path to the current log file, and the directory holding it.  Both are
// valid whether or not logging is enabled, so the UI can show where the file
// would be.
QString filePath();
QString dirPath();

// Size of the current log file in bytes; 0 when it does not exist.
qint64 sizeBytes();

// The last `maxLines` lines of the log, oldest first, for pasting into a bug
// report.  Empty when there is no log file.
QString tail(int maxLines);

// Delete the log file and its rotated predecessor, then start a fresh one.
void clear();

} // namespace logging