feat: add documentation for encrypted secrets and improve age key extraction logic

AGENTS.md

@@ -57,6 +57,18 @@ Inside the **pi** harness, the model ID is in `$PI_MODEL` (e.g. `moonshotai/Kimi
 
 **Edit with MCP**: Launch Jupyter Lab and use the builtin MCP server to edit the notebooks.
 
+### Encrypted secrets
+
+All required env vars are stored in `secrets.env`. You can load the env vars like this:
+
+```bash
+eval "$(task show-dotenv secrets)"
+```
+
+Set `SOPS_AGE_KEY_FILE=/home/$USER/.config/sops/age/keys.txt` to decrypt.
+
+You can run the notebook with `task run-jupyter-notebook setup-odoo.ipynb secrets`. This should automatically decrypt the `secrets.env` and load the env vars.
+
 ## Coding conventions
 
 ### Bash

AGENTS.md.template

@@ -50,6 +50,18 @@ When creating temporary fiels and scripts, use the `./tmp` directory.
 
 **About Regex**: Using regex patterns in Jupyter notebook cells is hard to edit for @Clanker tools. Create a Python file in a `./lib` folder that imports the necessary function to perform regex searches and replacements.
 
+### Encrypted secrets
+
+All required env vars are stored in `secrets.env`. You can load the env vars like this:
+
+```bash
+eval "$(task show-dotenv secrets)"
+```
+
+Set `SOPS_AGE_KEY_FILE=/home/$USER/.config/sops/age/keys.txt` to decrypt.
+
+You can run the notebook with `task run-jupyter-notebook setup-odoo.ipynb secrets`. This should automatically decrypt the `secrets.env` and load the env vars.
+
 ## Project structure
 
 @Clanker this is specific to every project. Update according to your discoveries.

bin/load-agekey-from-keepass

@@ -17,12 +17,38 @@ remove-agekey-block() {
         elif [[ "$line" == '# public key:'* ]]; then
             block_public_key="${line#\# public key: }"
             block_lines+=("$line")
-        elif [[ "$line" == '#'* ]]; then
+        elif [[ "$line" == '#'"*" ]]; then
             block_lines+=("$line")
         fi
     done < "$key_file"
 }
 
+extract-agekey-block() {
+    local target_public_key="$1"
+    local key_file="$2"
+    local -a block_lines=()
+    local block_public_key=""
+
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        if [[ "$line" == AGE-SECRET-KEY-* ]]; then
+            block_lines+=("$line")
+            if [[ "$block_public_key" == "$target_public_key" ]]; then
+                printf '%s\n' "${block_lines[@]}"
+                return 0
+            fi
+            block_lines=()
+            block_public_key=""
+        elif [[ "$line" == '# public key:'* ]]; then
+            block_public_key="${line#\# public key: }"
+            block_lines+=("$line")
+        elif [[ "$line" == '#'"*" ]]; then
+            block_lines+=("$line")
+        fi
+    done < "$key_file"
+
+    return 1
+}
+
 load-agekey-from-keepass() {
     local project_name
     project_name=$(basename -s .git "$(git remote get-url origin 2>/dev/null)" 2>/dev/null)
@@ -55,10 +81,28 @@ load-agekey-from-keepass() {
         return 1
     fi
 
+    if [[ -f "$age_key_file" ]]; then
+        local existing_block
+        existing_block=$(mktemp)
+        if extract-agekey-block "$public_key" "$age_key_file" > "$existing_block"; then
+            if diff -q "$existing_block" "$attachment" >/dev/null 2>&1; then
+                echo "Age key '$key_name' is already present and identical in $age_key_file."
+                rm -f "$attachment" "$existing_block"
+                return 0
+            else
+                echo "Error: Age key '$key_name' already exists in $age_key_file but differs from KeePassXC entry."
+                echo "Refusing to overwrite local key. Remove the existing key manually if you want to replace it."
+                rm -f "$attachment" "$existing_block"
+                return 1
+            fi
+        fi
+        rm -f "$existing_block"
+    fi
+
     local tmp_key_file
     tmp_key_file="${age_key_file}.tmp"
     if [[ -f "$age_key_file" ]]; then
-        remove-agekey-block "$public_key" "$age_key_file" > "$tmp_key_file"
+        cp "$age_key_file" "$tmp_key_file"
     else
         : > "$tmp_key_file"
     fi