refactor(preferences): 🚚 better heading for worker preferences in file

README.md

@@ -113,7 +113,7 @@
 
 ## 🌟 About the Project
 
-Go Hass Agent is an application to expose sensors, controls and events from a
+Go Hass Agent is an application to expose sensors, controls, and events from a
 device to Home Assistant. You can think of it as something similar to the [Home
 Assistant companion app](https://companion.home-assistant.io/) for mobile
 devices, but for your desktop, server, Raspberry Pi, Arduino, toaster, whatever.
@@ -124,7 +124,7 @@ running on. You can extend it with additional sensors and controls by hooking it
 up to MQTT. You can extend it **even further** with your own custom sensors and
 controls with scripts/programs.
 
-You can then use these sensors, controls or events in any automations and
+You can then use these sensors, controls, or events in any automations and
 dashboards, just like the companion app or any other “thing” you've added into
 Home Assistant.
 
@@ -167,7 +167,7 @@ this app:
 - Monitor CPU load, disk usage and any temperature sensors emitted from the
   device.
 - Receive notifications from Home Assistant on your desktop/laptop. Potentially
-  based on or utilising any of the data above.
+  based on or utilizing any of the data above.
 
 [⬆️ Back to Top](#-table-of-contents)
 
@@ -188,11 +188,11 @@ this app:
   changes.
   - Via D-Bus (requires [XDG Desktop Portal
   Support](https://flatpak.github.io/xdg-desktop-portal/docs/) support).
-  - Can be disabled via `worker_prefs.app_sensors.disabled` [preference](#️-preferences).
+  - Can be disabled via `worker.app_sensors.disabled` [preference](#️-preferences).
 - Desktop Settings:
-  - **Accent Colour** (the hex code representing the accent colour of the desktop
+  - **Accent Color** (the hex code representing the accent color of the desktop
   environment in use) and **Theme Type** (whether a dark or light desktop theme is
-  detected). Updated when theme or colour changes.
+  detected). Updated when theme or color changes.
   - Via D-Bus (requires [XDG Desktop Portal
   Support](https://flatpak.github.io/xdg-desktop-portal/docs/) support).
 - Media:
@@ -208,7 +208,7 @@ this app:
   - **Battery State** (the current battery state, e.g., charging/discharging).
     Updated When state changes.
   - All battery sensors require D-Bus and
-    [Upower](https://upower.freedesktop.org/) support.
+    [UPower](https://upower.freedesktop.org/) support.
 - Memory Stats:
   - **Memory Total** (total memory on the system, in B).
   - **Memory Available** (current memory available/free, in B).
@@ -239,31 +239,31 @@ this app:
       Updated when strength changes.
     - **BSSID** (the BSSID of the Wi-Fi network). Updated when BSSID changes.
   - **Device/Link State**
-    - Via netlink.
+    - Via Netlink.
   - **Bytes Received/Sent** (in B). Updated ~every 5s.
     - Per network device/link and total.
-    - Via netlink.
+    - Via Netlink.
   - **Bytes Received/Sent Rate** (transfer rate, in B/s). Updated ~every 5
     seconds. Via ProcFS.
     - Per network device/link and total.
-    - Via netlink.
+    - Via Netlink.
   - You can ignore some devices from generating these sensors, see the
-    `worker_prefs.network_sensors.ignored_devices` [preference](#️-preferences).
+    `worker.network_sensors.ignored_devices` [preference](#️-preferences).
 - CPU:
   - **Load Average (1/5/15 min)**. Updated ~every 1 minute. Via ProcFS.
   - **CPU Usage** (in %). Both total (all-cores) and per-core. Updated ~every 10
     seconds. Via ProcFS.
     - Attributes include breakdown of CPU time per state (i.e., user, idle,
       servicing interrupts, etc.).
     - The polling frequency can be changed in the [preferences](#️-preferences) through the following:
-      - `worker_prefs.cpu_usage_sensors.update_interval`
+      - `worker.cpu_usage_sensors.update_interval`
 - - **CPU Core Frequency** (in Hz). Per-core. Updated ~every 10 seconds. Via
     ProcFS.
     - Attributes include current driver and governor in use.
     - CPU Frequency sensors can be disabled and/or the polling frequency changed
       in the [preferences](#️-preferences) through the following:
-      - `worker_prefs.cpu_freq_sensors.disabled`
-      - `worker_prefs.cpu_freq_sensors.update_interval`
+      - `worker.cpu_freq_sensors.disabled`
+      - `worker.cpu_freq_sensors.update_interval`
 - Power Related Details:
   - **Power Profile** (the current power profile as set by the
     power-profiles-daemon). Updated when profile changes.
@@ -305,8 +305,8 @@ this app:
     - Extracted from the `/sys/class/hwmon` file system.
     - Hardware sensors can be disabled and/or the polling frequency changed
       in the [preferences](#️-preferences) through the following:
-      - `worker_prefs.system_sensors.disable_hwmon`
-      - `worker_prefs.system_sensors.hwmon_sensor_update_interval`
+      - `worker.system_sensors.disable_hwmon`
+      - `worker.system_sensors.hwmon_sensor_update_interval`
 
 #### 🕹️ Controls
 
@@ -315,28 +315,28 @@ this app:
 > MQTT](#-mqtt-sensors-and-controls)
 
 - Media Controls:
-  - **Volume Control** Adjust the volume on the default audio output device.
-  - **Volume Mute** Mute/Unmute the default audio output device.
-  - **Webcam Control** Start/stop a webcam and view the video in Home Assistant.
+  - **Volume Control**: Adjust the volume on the default audio output device.
+  - **Volume Mute**: Mute/Unmute the default audio output device.
+  - **Webcam Control**: Start/stop a webcam and view the video in Home Assistant.
     - Requires a webcam that is exposed via V4L2 (VideoForLinux2).
   - You can set some preferences (for e.g., the camera device and video
     properties) if the defaults are not satisfactory, see the
     `media_controls_preferences.toml` file in the [preferences](#️-preferences).
 - Power Controls:
-  - **Lock/Unlock Screen/Screensaver** Locks/unlocks the session for the user
+  - **Lock/Unlock Screen/Screensaver**: Locks/unlocks the session for the user
     running Go Hass Agent.
-  - **Suspend** Will (instantly) suspend (the system state is saved to RAM and
-    the CPU is turned off) the device running Go Hass Agent.
-  - **Hibernate** Will (instantly) hibernate (the system state is saved to disk
-    and the machine is powered down) the device running Go Hass Agent.
-  - **Power Off** Will (instantly) power off the device running Go Hass Agent.
-  - **Reboot** Will (instantly) reboot the device running Go Hass Agent.
+  - **Suspend**: (instantly) suspend (the system state saved to RAM and
+    the CPU turned off) the device running Go Hass Agent.
+  - **Hibernate**: (instantly) hibernate (the system state saved to disk
+    and the machine powered down) the device running Go Hass Agent.
+  - **Power Off**: (instantly) power off the device running Go Hass Agent.
+  - **Reboot**: (instantly) reboot the device running Go Hass Agent.
   - Power controls require a system configured with `systemd-logind` (and D-Bus)
     support.
 
 #### 📢 Events
 
-- User sessions (login/logout) events.
+- **User sessions (login/logout) events**.
   - Requires a system configured with `systemd-logind`.
   - Event structures:
 
@@ -352,7 +352,7 @@ this app:
       user: myuser # username.
     ```
 
-- Out Of Memory (OOM) events.
+- **Out Of Memory (OOM) events**.
   - Requires a system configured with `systemd-oomd` enabled.
   - Event structure:
 
@@ -367,12 +367,12 @@ this app:
 
 **Sensors:**
 
-- **Go Hass Agent Version**. Updated on agent start.
-- **External IP Addresses**. All external IP addresses (IPv4/6) of the device
+- **Go Hass Agent Version**: Updated on agent start.
+- **External IP Addresses**: All external IP addresses (IPv4/6) of the device
   running the agent.
   - Can be disabled in the [preferences](#️-preferences) with the
-    `worker_prefs.external_ip_sensor.disabled` preference.
-- **Connection Latency**. Total connection time (in milliseconds) to connect to
+    `worker.external_ip_sensor.disabled` preference.
+- **Connection Latency**: Total connection time (in milliseconds) to connect to
   Home Assistant from the device running Go Hass Agent. Additional times shown
   as attributes.
 
@@ -581,8 +581,7 @@ podman run \
   ...other options... \
   --volume /proc:/host/proc:ro --volume /sys:/host/sys:ro --volume /dev:/host/dev:ro \
   --env PROCFS_ROOT=/host/proc --env SYSFS_ROOT=/host/sys --env DEVFS_ROOT=/host/dev \
-  ...other options... \
-...
+  ...other options...
 ```
 
 ### 🔄 Regular Usage
@@ -606,7 +605,7 @@ The preferences file (`preferences.toml`) is located in
 - Windows: `LocalAppData`.
 
 > [!WARNING]
-> Only the individual sensor preferences under the `worker_prefs`
+> Only the individual sensor preferences under the `worker`
 > sections should be edited manually.
 
 [⬆️ Back to Top](#-table-of-contents)
@@ -638,7 +637,7 @@ run on its own schedule, specified using a Cron syntax.
 
 Any typical scripting language that can be invoked with a shebang can be used
 for scripts. All scripts do not need to be written in the same language. So or
-the typical shells can be used such as Bash, Sh, Zsh, Fish, Elvish. Scripting
+the typical shells can be used such as `bash`, `sh`, `zsh`, `fish`, etc. Scripting
 languages such as Python, Perl, and Ruby can also be used.
 
 #### Output Format
@@ -791,7 +790,7 @@ However, more cron formats are supported:
 
 Running scripts can be dangerous, especially if the script does not have robust
 error-handling or whose origin is untrusted or unknown. Go Hass Agent makes no
-attempt to do any analysis or sanitisation of script output, other than ensuring
+attempt to do any analysis or sanitization of script output, other than ensuring
 the output is a [supported format](#output-format). As such, ensure you trust
 and understand what the script does and all possible outputs that the script can
 produce. Scripts are run by the agent and have the permissions of the user
@@ -867,7 +866,7 @@ The agent will subscribe to the MQTT topic `gohassagent/HOSTNAME/dbuscommand`
 (where `HOSTNAME` is the short hostname of the device running Go Hass Agent)  on
 the configured MQTT broker and listens for messages with a JSON payload (shown
 below) that contains details of the D-Bus method to call. When a message is
-recieved, the method will be executed. The easiest way to use this feature is
+received, the method will be executed. The easiest way to use this feature is
 with the `mqtt.publish` service in Home Assistant.
 
 As an example, the following will create a notification on the device running Go
@@ -1107,8 +1106,8 @@ podman build --file ./Dockerfile --platform linux/arm/v7 --tag go-hass-agent
 ```
 
 > [!NOTE]
-> By default, the container will run as a user with uid/gid 1000/1000.
-> You can pick a different uid/gid when building by adding `--build-arg UID=999`
+> By default, the container will run as a user with UID/GID 1000/1000.
+> You can pick a different UID/GID when building by adding `--build-arg UID=999`
 > and `--build-arg GID=999` (adjusting the values as appropriate).
 
 [⬆️ Back to Top](#-table-of-contents)
@@ -1167,7 +1166,7 @@ whereas you may wish to change the unit of measurement to gigabytes (GB).
 
 - There is currently some limited support for disabling certain _groups_ of
 sensors. In the [preferences](#️-preferences), under the
-`worker_prefs` sections, you can find some controls to disable some sensor
+`worker` sections, you can find some controls to disable some sensor
 groups.
 - Alternatively, you can disable the corresponding sensor entity in Home Assistant,
  and the agent will stop sending updates for it.
@@ -1270,8 +1269,8 @@ execution.
 used to run the agent as a service.
 - You will still need to register the agent manually before starting as a service.
 See the command for registration in the [README](#-running-headless).
-- You will also need to ensure your user has “lingering” enabled.  Run `loginctl
-list-users` and check that your user has **LINGER** set to “yes”. If not, run
+- You will also need to ensure your user has “lingering” enabled.  Run
+`loginctl list-users` and check that your user has `LINGER` set to “yes”. If not, run
 `loginctl enable-linger`.
 - Once you have registered the agent and enabled lingering for your user. Enable
 the service and start it with the command: `systemctl --user enable

docs/BREAKING_CHANGES.md

@@ -4,28 +4,29 @@
 
 - [BREAKING CHANGES](#breaking-changes)
   - [Table of Contents](#table-of-contents)
-  - [v11.0.0](#v1100)
+  - [Version 11.0.0](#version-1100)
     - [Worker and Agent preferences merge](#worker-and-agent-preferences-merge)
       - [What you need to do](#what-you-need-to-do)
-  - [v10.0.0](#v1000)
+  - [Version 10.0.0](#version-1000)
     - [New preferences file location and format](#new-preferences-file-location-and-format)
       - [What you need to do](#what-you-need-to-do-1)
         - [Run the upgrade command](#run-the-upgrade-command)
         - [Manual upgrade steps (if the upgrade command failed)](#manual-upgrade-steps-if-the-upgrade-command-failed)
-    - [Log file location normalisation](#log-file-location-normalisation)
+    - [Log file location normalization](#log-file-location-normalization)
       - [What you need to do](#what-you-need-to-do-2)
     - [MQTT Device renamed](#mqtt-device-renamed)
       - [What you need to do](#what-you-need-to-do-3)
     - [Power controls renaming and consolidation (when using MQTT)](#power-controls-renaming-and-consolidation-when-using-mqtt)
       - [What you need to do](#what-you-need-to-do-4)
 
-## v11.0.0
+## Version 11.0.0
 
 ### Worker and Agent preferences merge
 
-Individual worker preferences, which were previously in their own files under
-the [configuration directory](../README#️-preferences), now live in
-the agent preferences file (`preferences.toml`).
+Individual worker preferences, for adjusting preferences around different sensor
+groups, were previously in their own files under the [configuration
+directory](../README#️-preferences). They now live in the agent preferences file
+(`preferences.toml`), under the `worker` heading.
 
 #### What you need to do
 
@@ -38,20 +39,20 @@ relevant preferences mentioned.
 Once you have migrated any custom preferences, it is safe to delete the
 individual preferences files (named `*_preferences.toml`).
 
-## v10.0.0
+## Version 10.0.0
 
 ### New preferences file location and format
 
 The agent preferences file (`preferences.toml`) location has changed. The
-configuration is now located in `~/.config/go-hass-agent/`.
+configuration can be found in `~/.config/go-hass-agent/`.
 
 The format of the file has changed as well it now contains more structure.
 
 #### What you need to do
 
 ##### Run the upgrade command
 
-An `upgrade` command has been added to Go Hass Agent that will attempt to
+The `upgrade` command has been added to Go Hass Agent that will attempt to
 migrate a preferences file from an older version to the location and format used
 by the new version. It uses reasonable efforts to migrate but may not succeed
 and is harmless to run regardless. **It is the recommended remediation for this
@@ -122,7 +123,7 @@ To re-register:
 
 [⬆️ Back to Top](#table-of-contents)
 
-### Log file location normalisation
+### Log file location normalization
 
 The agent will now write to a log file at
 `~/.config/go-hass-agent/go-hass-agent.log`.
@@ -143,18 +144,18 @@ when running the agent.
 
 The naming of Go Hass Agent in the MQTT integration in Home Assistant has
 changed. It is now named after the hostname of the device running the agent,
-rather than the generic "Go Hass Agent". This makes it easier to navigate
+rather than the generic “Go Hass Agent”. This makes it easier to navigate
 between multiple devices running Go Hass Agent in Home Assistant.
 
 #### What you need to do
 
-As a result of this, you may end up with a deprecated, non-functional "Go Hass
-Agent" device entry in Home Assistant. It can safely be removed.
+As a result of this, you may end up with a deprecated, non-functional “Go Hass
+Agent” device entry in Home Assistant. It can safely be removed.
 
 > [!IMPORTANT]
 >
 > As the device has changed, existing automations or dashboards that are using
-> entities from the old "Go Hass Agent" may be broken. In most cases, the
+> entities from the old “Go Hass Agent” may be broken. In most cases, the
 > [repairs integration](https://www.home-assistant.io/integrations/repairs/)
 > will alert and direct you to make any adjustments needed.
 
@@ -201,7 +202,7 @@ by your device will be shown. Notably:
 
 #### What you need to do
 
-Follow the [what you need to do](#what-you-need-to-do-2) for the MQTT device
+Follow [what you need to do](#what-you-need-to-do-2) for the MQTT device
 rename breaking change, if not done already.
 
 [⬆️ Back to Top](#table-of-contents)

internal/preferences/worker.go

@@ -13,6 +13,10 @@ import (
 	"github.com/joshuar/go-hass-agent/internal/validation"
 )
 
+const (
+	workerPrefsPrefix = "worker"
+)
+
 // CommonWorkerPrefs contains worker preferences that all workers can/should
 // implement. For e.g., a toggle to completely disable the worker.
 type CommonWorkerPrefs struct {
@@ -35,7 +39,7 @@ var (
 
 // LoadWorker reads the given worker's preferences from file.
 func LoadWorker[T any](worker Worker[T]) (*T, error) {
-	prefsKey := "worker_prefs." + worker.PreferencesID()
+	prefsKey := workerPrefsPrefix + "." + worker.PreferencesID()
 	// Load default worker prefs.
 	prefs := worker.DefaultPreferences()
 
@@ -91,7 +95,7 @@ func SaveWorker[T any](worker Worker[T], prefs T) error {
 	}
 
 	// Merge the worker preferences into the preferences file.
-	if err := prefsSrc.Set("worker_prefs."+worker.PreferencesID(), prefsMaps); err != nil {
+	if err := prefsSrc.Set(workerPrefsPrefix+"."+worker.PreferencesID(), prefsMaps); err != nil {
 		return fmt.Errorf("%w: %w", ErrSaveWorkerPrefs, err)
 	}