home-environment: add home.uid option

Add a home.uid option similar to home.username. When set, the
activation script verifies the current UID matches the expected
value using the new checkUid function.

When using the NixOS or nix-darwin modules, home.uid is
auto-discovered from users.users.<name>.uid when that value
is set.

This is useful for constructing paths that depend on the user's
UID, such as /run/user/<uid> paths for gpg-agent sockets or
other user-specific runtime directories.

modules/lib-bash/activation-init.sh

@@ -117,6 +117,17 @@ function checkHomeDirectory() {
   fi
 }
 
+function checkUid() {
+  local expectedUid="$1"
+  local actualUid
+  actualUid="$(id -u)"
+
+  if [[ "$actualUid" != "$expectedUid" ]]; then
+    _iError 'Error: UID is "%s" but we expect "%s"' "$actualUid" "$expectedUid"
+    exit 1
+  fi
+}
+
 # Note, the VERBOSE_ECHO variable is deprecated and should not be used inside
 # the Home Manager project. It is provided here for backwards compatibility.
 if [[ -v VERBOSE ]]; then