[Improvement] User hook directories for omacase events (hooks/<event>.d)

[splaice]

Quattro feature

Omarchy 4 runs user-owned executable scripts from ~/.config/omarchy/hooks/<event>.d/ at defined moments: theme-set.d (theme slug in $1), post-update.d, post-boot.d, battery-low.d, font-set.d. It makes the system user-extensible without forking.

Omacase fit

Omacase already has the natural firing points and the config-dir precedent (~/.config/omacase/login-items):

• theme-set.d — end of omacase theme (slug in $1); lets users retarget apps Omacase doesn't theme
• post-update.d — end of omacase update
• post-login.d — OmacaseLauncher runs it after opening login-items (generalizes the launcher beyond open -a)
• pre-backup.d / post-restore.d — optional later

Proposed shape

• run_hooks <event> [args…] in lib/common.sh: iterate ~/.config/omacase/hooks/<event>.d/*, executable files only, each with a timeout, failures warn-not-abort, skipped entirely in dry-run with a log line
• Call sites at the three events above; document in README; doctor warns on non-executable hook files
• Security note in the header: hooks are user-owned arbitrary code by design (same trust as shell rc files); Omacase never ships hook content

Scope

Future release. High leverage for small code; also the extension point that keeps feature requests from becoming core code.

🤖 Generated with Claude Code

[splaice]

Implementation plan

Self-contained; needs only this comment and the repo.

Background

Quattro-style user hook directories: executable scripts in ~/.config/omacase/hooks/<event>.d/ run at defined moments. Firing points that exist today: end of omacase theme (lib/theme.sh, after _theme_reload/wallpaper — the success line at ~line 58), end of omacase update (lib/update.sh, before the final converged/success), and OmacaseLauncher's login pass (assets/launcher/OmacaseLauncher.sh). Config-dir precedent: ~/.config/omacase/ already holds login-items.

Change 1 — run_hooks in lib/common.sh

# run_hooks <event> [args…] — execute user hooks from
# ~/.config/omacase/hooks/<event>.d/, alphabetically. Hooks are user-owned
# arbitrary code BY DESIGN (same trust as ~/.zshrc); Omacase never ships hook
# content. Failures warn, never abort. Skipped in dry-run.
run_hooks() {
  local event="$1"; shift
  local dir="$HOME/.config/omacase/hooks/$event.d" hook
  [ -d "$dir" ] || return 0
  if is_dryrun; then log "[dry-run] would run hooks in $dir"; return 0; fi
  for hook in "$dir"/*; do
    [ -f "$hook" ] || continue
    if [ ! -x "$hook" ]; then warn "hook not executable, skipping: $hook"; continue; fi
    _run_hook_with_watchdog "$hook" "$@" || warn "hook failed: $(basename "$hook")"
  done
}

# macOS ships no `timeout`; 30s watchdog via background + kill. A hook that
# ignores TERM gets KILLed a beat later.
_run_hook_with_watchdog() {
  local hook="$1"; shift
  "$hook" "$@" & local pid=$!
  ( sleep 30; kill "$pid" 2>/dev/null; sleep 2; kill -9 "$pid" 2>/dev/null ) & local wd=$!
  local rc=0; wait "$pid" || rc=$?
  kill "$wd" 2>/dev/null; wait "$wd" 2>/dev/null || true
  return "$rc"
}

(Implementer: the watchdog subshell must not leave stray sleeps failing the suite — the kill "$wd" + wait pattern above handles it; verify with set -e active.)

Change 2 — call sites

• lib/theme.sh omacase_theme, after the theme fully applies (post _theme_wallpaper, before the success/notify): run_hooks theme-set "$name".
• lib/update.sh omacase_update, immediately before the final convergence report: run_hooks post-update.
• assets/launcher/OmacaseLauncher.sh: after the open -a loop, run ~/.config/omacase/hooks/post-login.d/* inline (the launcher script cannot source lib/common.sh — it's a standalone bundle executable; duplicate the tiny loop WITHOUT the watchdog, launchd is already supervising, and keep its no-set -e discipline). Keep both loops semantically identical; add a comment in each pointing at the other.

Change 3 — docs + doctor

• README: a "Hooks" subsection under configuration: the three events, args (theme-set gets the slug in $1), the trust note.
• lib/doctor.sh: warn on files in hook dirs that are not executable (they silently no-op otherwise).

Change 4 — tests

1. test_hooks_fire_with_args: temp HOME; hook writing $1 to a file; run_hooks theme-set nord → file contains nord.
2. test_hooks_failure_warns_not_aborts: failing hook + a second hook → second still runs, function returns 0, output warns.
3. test_hooks_skip_non_executable and test_hooks_dryrun_skips (OMACASE_DRYRUN=1 → nothing executed, [dry-run] line).
4. test_launcher_runs_post_login_hooks: run the launcher script with temp HOME/config: login-items empty + a post-login hook → hook ran.

Verification / done criteria

Suite green; shellcheck clean (watch SC2009/SC2046 around the watchdog). Live: a theme-set.d/50-echo hook logs the slug on omacase theme <name>; a sleeping hook (60s) is killed at ~30s without hanging the theme switch.

Branch + PR; body says Closes #23.