Update 5 files

- /home/.chezmoiscripts/universal/run_onchange_after_28-privoxy.tmpl
- /home/.chezmoiscripts/universal/run_onchange_after_27-tor.tmpl
- /home/.chezmoiscripts/universal/run_onchange_after_26-vscode-extensions.tmpl
- /home/.chezmoiscripts/universal/run_onchange_after_24-vpn-linux.tmpl
- /home/.chezmoiscripts/universal/run_onchange_after_41-vagrant-vmware-utility.tmpl

home/.chezmoiscripts/universal/run_onchange_after_24-vpn-linux.tmpl

@@ -1,5 +1,26 @@
 {{- if (eq .host.distro.family "linux") -}}
 #!/usr/bin/env bash
+# @file run_onchange_after_26-system-vscode-node-modules.tmpl
+# @brief Installs both OpenVPN and WireGuard VPN profiles on Linux devices.
+# @description
+#     This script installs OpenVPN and WireGuard VPN profiles. It does a few things to install the profiles and make sure
+#     they are usable by desktop users:
+#
+#     1. It ensures OpenVPN and `NetworkManager-*` plugins are installed (this allows you to see all the different VPN profile types available when you try to import a VPN profile on Linux devices)
+#     2. Imports the OpenVPN profiles stored in `${XDG_CONFIG_HOME:-$HOME/.config}/vpn`
+#     3. Applies the OpenVPN username and password to all the OpenVPN profiles (which can be passed in as `OVPN_USERNAME` and `OVPN_PASSWORD` if you use the environment variable method)
+#     4. Bypasses the OpenVPN connection for all the networks defined in `.host.vpn.excludedSubnets` (in the `home/.chezmoi.yaml.tmpl` file)
+#     5. Repeats the process for WireGuard by looping through all the `*.nmconnection` files stored in `${XDG_CONFIG_HOME:-$HOME/.config}/vpn` (username and password should already be stored in the encrypted files)
+#
+#     ## Creating VPN Profiles
+#
+#     More details on embedding your VPN profiles into your Install Doctor fork can be found by reading the [Secrets documentation](https://install.doctor/docs/customization/secrets#vpn-profiles).
+#
+#     ## Links
+#
+#     * [`run_onchange_after_24-vpn-linux.tmpl`](https://github.com/megabyte-labs/install.doctor/blob/master/home/.chezmoiscripts/universal/run_onchange_after_24-vpn-linux.tmpl)
+#     * [VPN profile folder](https://github.com/megabyte-labs/install.doctor/blob/master/home/dot_config/vpn)
+#     * [VPN profile documentation](https://install.doctor/docs/customization/secrets#vpn-profiles)
 
 {{ $ovpnUsername := (env "OVPN_USERNAME") }}
 {{ if (stat (joinPath .chezmoi.sourceDir ".chezmoitemplates" "secrets" "OVPN_USERNAME")) }}
@@ -16,7 +37,7 @@
 
 RESTART_NM=false
 
-### Ensure NetworkManager plugins are
+# @description Ensure `NetworkManager` plugins are
 # NOTE: By default, all the NetworkManager plugins are installed.
 if command -v apt-get > /dev/null; then
     sudo apt-get install -y network-manager*
@@ -28,7 +49,7 @@ else
     logg warn 'Unknown package manager - install OpenVPN / WireGuard / NetworkManager plugins individually'
 fi
 
-### Ensures NetworkManager event config folders are created
+# @description Ensures NetworkManager event config folders are created
 function ensureNetworkConfigs() {
     if [ ! -d /etc/network/if-up.d ]; then
         logg info 'Creating /etc/network/if-up.d folder'
@@ -40,12 +61,12 @@ function ensureNetworkConfigs() {
     fi
 }
 
-### Ensure NetworkManager is installed
+# @description Ensures `nmcli` (the CLI for NetworkManager) is available in the `PATH`
 if command -v nmcli > /dev/null; then
-    ### Setup OpenVPN profiles
+    # @description Sets up OpenVPN profiles
     if [ '{{ $ovpnUsername }}' != '' ] && [ '{{ $ovpnPassword }}' != '' ]; then
         find "${XDG_CONFIG_HOME:-$HOME/.config}/vpn" -type f -name "*.ovpn" | while read OVPN_FILE; do
-            ### Add the profile
+            # @description Adds the OpenVPN profiles by importing the `*.ovpn` files in `${XDG_CONFIG_HOME:-$HOME/.config}/vpn` and then applying the OpenVPN username and password
             logg info "Adding $OVPN_FILE to NetworkManager OpenVPN profiles"
             OVPN_NAME="$(basename "$OVPN_FILE" | sed 's/.ovpn$//')"
             nmcli connection import type openvpn file "$OVPN_FILE"
@@ -53,7 +74,7 @@ if command -v nmcli > /dev/null; then
             nmcli connection modify "$OVPN_NAME" vpn.secrets 'password={{- $ovpnPassword }}'
             nmcli connection modify "$OVPN_NAME" +vpn.data password-flags=0
 
-            ### Register the excluded subnets in the routeadd / routedel files
+            # @description Register the excluded subnets in the routeadd / routedel files
             for EXCLUDED_SUBNET in '{{ $removeShortcuts := join "' '" .host.vpn.excludedSubnets }}'; do
                 ensureNetworkConfigs
                 nmcli connection modify "$OVPN_NAME" +ipv4.routes "$EXCLUDED_SUBNET" | sudo tee -a /etc/network/if-up.d/routeadd
@@ -67,21 +88,21 @@ if command -v nmcli > /dev/null; then
     fi
 
 {{ if (stat (joinPath .host.home ".config" "age" "chezmoi.txt")) }}
-    ### Setup WireGuard profiles
+    # @description Setup WireGuard profiles
     if [ -d /etc/NetworkManager/system-connections ]; then
         find "${XDG_CONFIG_HOME:-$HOME/.config}/vpn" -type f -name "*.nmconnection" | while read WG_FILE; do
-            ### Ensure the WireGuard NetworkManager plugin is available
+            # @description Ensure the WireGuard NetworkManager plugin is available
             if [ ! -d /usr/lib/NetworkManager/nm-wireguard-service ]; then
                 logg info 'The `nm-wireguard-service` is not present'
                 logg info 'Installing the `nm-wireguard-service`'
             fi
 
-            ### Add the WireGuard profile
+            # @description Add the WireGuard profiles
             logg info "Adding $WG_FILE to /etc/NetworkManager/system-connections
             WG_FILENAME="$(basename "$WG_FILE")"
             chezmoi decrypt "$WG_FILE" | sudo tee "/etc/NetworkManager/system-connections/$WG_FILENAME"
 
-            ### Register the excluded subnets in the routeadd / routedel files
+            # @description Register the excluded subnets in the routeadd / routedel files
             for EXCLUDED_SUBNET in '{{ $removeShortcuts := join "' '" .host.vpn.excludedSubnets }}'; do
                 ensureNetworkConfigs
                 WG_PROFILE_NAME="$(echo "$WG_FILENAME" | sed 's/.nmconnection$//')"
@@ -95,7 +116,7 @@ if command -v nmcli > /dev/null; then
     fi
 {{ end -}}
 
-    ### Restart NetworkManager if changes were made and environment is not WSL
+    # @description Restart NetworkManager if changes were made and environment is not WSL
     if [ "$RESTART_NM" == 'true' ] && [[ ! "$(test -d proc && grep Microsoft /proc/version > /dev/null)" ]]; then
         logg info 'Restarting NetworkManager since VPN profiles were updated'
         sudo service NetworkManager restart

home/.chezmoiscripts/universal/run_onchange_after_26-vscode-extensions.tmpl

@@ -27,11 +27,12 @@
 #
 #     * [`run_onchange_after_26-vscode-extensions.tmpl`](https://github.com/megabyte-labs/install.doctor/blob/master/home/.chezmoiscripts/universal/run_onchange_after_26-vscode-extensions.tmpl)
 #     * [Visual Studio Code settings folder](https://github.com/megabyte-labs/install.doctor/blob/master/home/dot_config/Code/User)
+#     * [Visual Studio Code `extensions.json`](https://github.com/megabyte-labs/install.doctor/blob/master/home/dot_config/Code/User/extensions.json)
 
 {{ includeTemplate "universal/profile" }}
 {{ includeTemplate "universal/logg" }}
 
-### Install Visual Studio Code extensions
+# @description Install Visual Studio Code extensions if they are not already installed (by checking the `code --list-extensions` output)
 if command -v code > /dev/null; then
     EXTENSIONS="$(code --list-extensions)"
     jq -r '.recommendations[]' "${XDG_CONFIG_HOME:-$HOME/.config}/Code/User/extensions.json" | while read EXTENSION; do
@@ -47,7 +48,7 @@ else
     logg warn '`code` executable not available'
 fi
 
-### Install VSCodium extensions
+# @description Check for the presence of the `codium` command in the `PATH` and install extensions for VSCodium if it is present
 if command -v codium > /dev/null; then
     EXTENSIONS="$(codium --list-extensions)"
     jq -r '.recommendations[]' "${XDG_CONFIG_HOME:-$HOME/.config}/Code/User/extensions.json" | while read EXTENSION; do

home/.chezmoiscripts/universal/run_onchange_after_27-tor.tmpl

@@ -1,12 +1,27 @@
 {{- if and (ne .host.distro.family "windows") (ne .host.work true) -}}
 #!/usr/bin/env bash
+# @file run_onchange_after_27-tor.tmpl
+# @brief This script applies the Tor configuration stored at `${XDG_CONFIG_HOME:-HOME/.config}/tor/torrc` to the system and then restarts Tor
+# @description
+#     Tor is a network that uses onion routing, originally published by the US Navy. It is leveraged by privacy enthusiasts
+#     and other characters that deal with sensitive material, like journalists and people buying drugs on the internet.
+#     This script:
+#
+#     1. Determines the system configuration file location
+#     2. Applies the configuration stored at `${XDG_CONFIG_HOME:-HOME/.config}/tor/torrc`
+#     3. Enables and restarts the Tor service with the new configuration
+#
+#     ## Links
+#
+#     * [Script on GitHub](https://github.com/megabyte-labs/install.doctor/blob/master/home/.chezmoiscripts/universal/run_onchange_after_27-tor.tmpl)
+#     * [Tor configuration](https://github.com/megabyte-labs/install.doctor/tree/master/home/dot_config/tor/torrc)
 
 # tor config hash: {{ include (joinPath .host.home ".config" "tor" "torrc") | sha256sum }}
 
 {{ includeTemplate "universal/profile" }}
 {{ includeTemplate "universal/logg" }}
 
-### Apply system variables
+# @description Determine the Tor configuration location by checking whether the system is macOS or Linux
 if [ -d /Applications ] && [ -d /System ]; then
     # macOS
     TORRC_CONFIG_DIR=/usr/local/etc/tor
@@ -16,14 +31,14 @@ else
 fi
 TORRC_CONFIG="$TORRC_CONFIG_DIR/torrc"
 
-### Configure Tor
+# @description Apply the configuration if the `torrc` binary is available in the `PATH`
 if command -v toron > /dev/null; then
     if [ -d  "$TORRC_CONFIG_DIR" ]; then
-        # Copy config
+        # @description Copy the configuration from `${XDG_CONFIG_HOME:-$HOME/.config}/tor/torrc` to the system configuration file location
         sudo cp -f "${XDG_CONFIG_HOME:-$HOME/.config}/tor/torrc" "$TORRC_CONFIG"
         sudo chmod 600 "$TORRC_CONFIG"
 
-        # Restart / enable Tor
+        # @description Enable and restart the Tor service
         if [ -d /Applications ] && [ -d /System ]; then
             # macOS
             brew services restart tor

home/.chezmoiscripts/universal/run_onchange_after_28-privoxy.tmpl

@@ -1,12 +1,26 @@
 {{- if (ne .host.distro.family "windows") -}}
 #!/usr/bin/env bash
+# @file run_onchange_after_28-privoxy.tmpl
+# @brief This script applies the Privoxy configuration stored at `${XDG_CONFIG_HOME:-HOME/.config}/privoxy/config` to the system and then restarts Privoxy
+# @description
+#     Privoxy is a web proxy that can be combined with Tor to provide an HTTPS / HTTP proxy that can funnel all traffic
+#     through Tor. This script:
+#
+#     1. Determines the system configuration file location
+#     2. Applies the configuration stored at `${XDG_CONFIG_HOME:-HOME/.config}/privoxy/config`
+#     3. Enables and restarts the Privoxy service with the new configuration
+#
+#     ## Links
+#
+#     * [Script on GitHub](https://github.com/megabyte-labs/install.doctor/blob/master/home/.chezmoiscripts/universal/run_onchange_after_28-privoxy.tmpl)
+#     * [Privoxy configuration](https://github.com/megabyte-labs/install.doctor/tree/master/home/dot_config/privoxy/config)
 
 # privoxy config hash: {{ include (joinPath .host.home ".config" "privoxy" "config") | sha256sum }}
 
 {{ includeTemplate "universal/profile" }}
 {{ includeTemplate "universal/logg" }}
 
-### Apply system variables
+# @description Define the Privoxy configuration location based on whether system is macOS or Linux
 if [ -d /Applications ] && [ -d /System ]; then
     # macOS
     PRIVOXY_CONFIG_DIR=/usr/local/etc/privoxy
@@ -16,14 +30,14 @@ else
 fi
 PRIVOXY_CONFIG="$PRIVOXY_CONFIG_DIR/config"
 
-### Configure Privoxy
+# @description Copy Privoxy configuration stored at `${XDG_CONFIG_HOME:-HOME/.config}/privoxy/config` to the system location
 if command -v privoxy > /dev/null; then
     if [ -d  "$PRIVOXY_CONFIG_DIR" ]; then
         sudo cp -f "${XDG_CONFIG_HOME:-HOME/.config}/privoxy/config" "$PRIVOXY_CONFIG"
         sudo chmod 600 "$PRIVOXY_CONFIG"
         sudo chown privoxy:privoxy "$PRIVOXY_CONFIG"
 
-        # Restart / enable Privoxy
+        # @description Restart Privoxy after configuration is applied
         if [ -d /Applications ] && [ -d /System ]; then
             # macOS
             brew services restart privoxy

home/.chezmoiscripts/universal/run_onchange_after_41-vagrant-vmware-utility.tmpl

@@ -1,12 +1,28 @@
 {{- if ne .host.distro.family "windows" -}}
 #!/usr/bin/env bash
+# @file run_onchange_after_41-vagrant-vmware-utility.tmpl
+# @brief Installs the `vagrant-vmware-utility` if both Vagrant and VMWare are installed
+# @description
+#     This script first checks if `vagrant`, `vmware`, and `vagrant-vmware-utility` are available in the `PATH`. If they are present, then the script
+#     configures the [`vagrant-vmware-utility`](https://developer.hashicorp.com/vagrant/docs/providers/vmware/vagrant-vmware-utility) by generating the required security certificates and enabling the service.
+#     This system package enables the capability of controlling both VMWare Workstation and VMWare Fusion with Vagrant.
+#
+#     Since this script runs only when `vagrant`, `vmware`, and `vagrant-vmware-utility` are in the `PATH`, this means that it will run
+#     when you use an installation template that includes all three pieces of software in the software list defined in
+#     `home/.chezmoidata.yaml`.
+#
+#     ## Links
+#
+#     * [`run_onchange_after_41-vagrant-vmware-utility.tmpl`](https://github.com/megabyte-labs/install.doctor/blob/master/home/.chezmoiscripts/universal/run_onchange_after_41-vagrant-vmware-utiltiy.tmpl)
+#     * [Vagrant VMWare Utility on GitHub](https://github.com/hashicorp/vagrant-vmware-desktop)
+#     * [`home/.chezmoidata.yaml`](https://github.com/megabyte-labs/install.doctor/blob/master/home/.chezmoidata.yaml)
 
 {{ includeTemplate "universal/profile" }}
 {{ includeTemplate "universal/logg" }}
 
-### Only run logic if both Vagrant and VMWare are installed
+# @description Only run logic if both Vagrant and VMWare are installed
 if command -v vagrant > /dev/null && command -v vmware > /dev/null; then
-    ### Vagrant VMWare Utility configuration
+    # @description  Vagrant VMWare Utility configuration
     if command -v vagrant-vmware-utility > /dev/null; then
         if [ -f /usr/local/bin/certificates/vagrant-utility.key ]; then
             logg info 'Assuming Vagrant VMWare Utility certificates have been properly generated since /usr/local/bin/certificates/vagrant-utility.key is present'