feat: add wallpaper post-hook for dynamic theming (#61)

* feat: add wallpaper post-hook for dynamic theming

Adds support for running custom shell commands after wallpaper changes
via the `wallpaper.postHook` config option in `~/.config/caelestia/cli.json`.

The wallpaper path is made available to the hook via the $WALLPAPER_PATH
environment variable. This enables integration with tools like `matugen`
or `pywal` for dynamic theming based on wallpaper colors.

The hook runs after apply_colours() in set_wallpaper(), ensuring it
executes for all wallpaper change methods (UI, IPC, and direct CLI).

* Replaced comment in example config with no-op command

2 files changed, 19 insertions, 0 deletions

diff --git a/README.md b/README.md
index f4006a3..5c9e960 100644
--- a/README.md
+++ b/README.md
@@ -133,6 +133,9 @@ All configuration options are in `~/.config/caelestia/cli.json`.
     "record": {
         "extraArgs": []
     },
+    "wallpaper": {
+        "postHook": "echo $WALLPAPER_PATH"  
+    },
     "theme": {
         "enableTerm": true,
         "enableHypr": true,
diff --git a/src/caelestia/utils/wallpaper.py b/src/caelestia/utils/wallpaper.py
index 9f75091..ff0d209 100644
--- a/src/caelestia/utils/wallpaper.py
+++ b/src/caelestia/utils/wallpaper.py
@@ -1,5 +1,7 @@
 import json
+import os
 import random
+import subprocess
 from argparse import Namespace
 from pathlib import Path
 
@@ -11,6 +13,7 @@ from caelestia.utils.hypr import message
 from caelestia.utils.material import get_colours_for_image
 from caelestia.utils.paths import (
     compute_hash,
+    user_config_path,
     wallpaper_link_path,
     wallpaper_path_path,
     wallpaper_thumbnail_path,
@@ -158,6 +161,19 @@ def set_wallpaper(wall: Path | str, no_smart: bool) -> None:
     scheme.update_colours()
     apply_colours(scheme.colours, scheme.mode)
 
+    # Run custom post-hook if configured
+    try:
+        cfg = json.loads(user_config_path.read_text()).get("wallpaper", {})
+        if post_hook := cfg.get("postHook"):
+            subprocess.run(
+                post_hook,
+                shell=True,
+                env={**os.environ, "WALLPAPER_PATH": str(wall)},
+                stderr=subprocess.DEVNULL,
+            )
+    except (FileNotFoundError, json.JSONDecodeError):
+        pass
+
 
 def set_random(args: Namespace) -> None:
     wallpapers = get_wallpapers(args)