feat: Implement intelligent dry-run logic for portracker and update standards

.agent/instructions.md

@@ -11,14 +11,55 @@ When maintaining this repository, you MUST adhere to the following rules based o
 
 2. **Setup Scripts**:
    - If a setup script does not exist, CREATE one named `create_<service>_folders.sh` in the service directory.
-   - Use the following template for scripts:
+   - Use the following template for scripts (Intelligent Dry-run by default):
      ```bash
      #!/bin/bash
-     BASE="/volume1/docker/service_name"
-     MEDIA="/volume1/media/service_data"
-     mkdir -p "$BASE/config" "$BASE/data" "$MEDIA"
-     chown -R PUID:PGID "$BASE" "$MEDIA"
-     chmod -R 750 "$BASE" "$MEDIA"
+     DRY_RUN=true
+     if [[ "$1" == "--run" || "$1" == "-r" ]]; then DRY_RUN=false; fi
+
+     if [ "$DRY_RUN" = "true" ]; then
+         echo "--- DRY RUN MODE ---"
+         echo "To apply changes, run: sudo bash $0 --run"
+         echo "--------------------"
+     fi
+
+     run_mkdir() {
+         local path=$1
+         if [ -d "$path" ]; then
+             echo "[OK] Folder exists, no changes will be made: $path"
+         else
+             if [ "$DRY_RUN" = "true" ]; then echo "[WILL CREATE] Folder: $path"; else mkdir -p "$path"; fi
+         fi
+     }
+
+     run_chown_recursive() {
+         local owner=$1; local path=$2
+         local uid=${owner%%:*}; local gid=${owner#*:}
+         
+         if [ ! -d "$path" ]; then
+             if [ "$DRY_RUN" = "true" ]; then echo "[WILL SET] Owner to $owner upon creation: $path"; else chown -R "$owner" "$path"; fi
+             return
+         fi
+
+         if find "$path" \( ! -uid "$uid" -o ! -gid "$gid" \) | grep -q .; then
+             if [ "$DRY_RUN" = "true" ]; then echo "[WILL CHANGE] Owner to $owner (recursive): $path"; else chown -R "$owner" "$path"; fi
+         else
+             echo "[OK] Owner is $owner, no changes will be made: $path"
+         fi
+     }
+     
+     run_chmod_recursive() {
+         local mode=$1; local path=$2
+         if [ ! -d "$path" ]; then
+             if [ "$DRY_RUN" = "true" ]; then echo "[WILL SET] Permissions to $mode upon creation: $path"; else chmod -R "$mode" "$path"; fi
+             return
+         fi
+         if find "$path" ! -perm -"$mode" | grep -q .; then
+             if [ "$DRY_RUN" = "true" ]; then echo "[WILL CHANGE] Permissions to $mode (recursive): $path"; else chmod -R "$mode" "$path"; fi
+         else
+             echo "[OK] Permissions are $mode, no changes will be made: $path"
+         fi
+     }
      ```
    - Ensure the script is idempotent (safe to run multiple times).