From 1abdd45821c59eba8c1e087629909fc455dfd995 Mon Sep 17 00:00:00 2001
From: DavHau <d.hauer.it@gmail.com>
Date: Tue, 12 Aug 2025 15:57:04 +0700
Subject: [PATCH] vars: add doc comments for fix() and health_check()

---
 pkgs/clan-cli/clan_cli/vars/_types.py         | 30 ++++++++++++++++-
 .../clan_cli/vars/secret_modules/sops.py      | 33 +++++++++++++++++--
 2 files changed, 60 insertions(+), 3 deletions(-)

diff --git a/pkgs/clan-cli/clan_cli/vars/_types.py b/pkgs/clan-cli/clan_cli/vars/_types.py
index 2280e24a7..0eddf4ad6 100644
--- a/pkgs/clan-cli/clan_cli/vars/_types.py
+++ b/pkgs/clan-cli/clan_cli/vars/_types.py
@@ -81,6 +81,20 @@ class StoreBase(ABC):
         generators: list["Generator"] | None = None,
         file_name: str | None = None,
     ) -> str | None:
+        """
+        Check the health of the store for the given machine and generators.
+
+        This method detects any issues or inconsistencies in the store that may
+        require fixing (e.g., outdated encryption keys, missing permissions).
+
+        Args:
+            machine: The name of the machine to check
+            generators: List of generators to check. If None, checks all generators for the machine
+            file_name: Optional specific file to check. If provided, only checks that file
+
+        Returns:
+            str | None: An error message describing issues found, or None if everything is healthy
+        """
         return None
 
     def fix(
@@ -89,7 +103,21 @@ class StoreBase(ABC):
         generators: list["Generator"] | None = None,
         file_name: str | None = None,
     ) -> None:
-        return None
+        """
+        Fix any issues with the store for the given machine and generators.
+
+        This method is intended to repair or update the store when inconsistencies
+        are detected (e.g., re-encrypting secrets with new keys, fixing permissions).
+
+        Args:
+            machine: The name of the machine to fix vars for
+            generators: List of generators to fix. If None, fixes all generators for the machine
+            file_name: Optional specific file to fix. If provided, only fixes that file
+
+        Returns:
+            None
+        """
+        return
 
     def backend_collision_error(self, folder: Path) -> None:
         msg = (
diff --git a/pkgs/clan-cli/clan_cli/vars/secret_modules/sops.py b/pkgs/clan-cli/clan_cli/vars/secret_modules/sops.py
index 40b7a188d..695d55c76 100644
--- a/pkgs/clan-cli/clan_cli/vars/secret_modules/sops.py
+++ b/pkgs/clan-cli/clan_cli/vars/secret_modules/sops.py
@@ -116,8 +116,22 @@ class SecretStore(StoreBase):
         file_name: str | None = None,
     ) -> str | None:
         """
-        Apply local updates to secrets like re-encrypting with missing keys
-            when new users were added.
+        Check if SOPS secrets need to be re-encrypted due to recipient changes.
+
+        This method verifies that all secrets are properly encrypted with the current
+        set of recipient keys. It detects when new users or machines have been added
+        to the clan but secrets haven't been re-encrypted to grant them access.
+
+        Args:
+            machine: The name of the machine to check secrets for
+            generators: List of generators to check. If None, checks all generators for the machine
+            file_name: Optional specific file to check. If provided, only checks that file
+
+        Returns:
+            str | None: A message describing which secrets need updating, or None if all secrets are up-to-date
+
+        Raises:
+            ClanError: If the specified file_name is not found
         """
 
         if generators is None:
@@ -315,6 +329,21 @@ class SecretStore(StoreBase):
         generators: list[Generator] | None = None,
         file_name: str | None = None,
     ) -> None:
+        """
+        Fix sops secrets by re-encrypting them with the current set of recipient keys.
+
+        This method updates secrets when recipients have changed (e.g., new admin users
+        were added to the clan). It ensures all authorized recipients have access to the
+        secrets and removes access from any removed recipients.
+
+        Args:
+            machine: The name of the machine to fix secrets for
+            generators: List of generators to fix. If None, fixes all generators for the machine
+            file_name: Optional specific file to fix. If provided, only fixes that file
+
+        Raises:
+            ClanError: If the specified file_name is not found
+        """
         from clan_cli.secrets.secrets import update_keys
 
         if generators is None: