Module hook 

Hook system — run user-supplied scripts around yui apply.

Scripts live at $DOTFILES/<config.script> (idiomatic place is .yui/bin/<name>.sh). They’re plain executables — no yui imports, no special protocol. yui just decides when to invoke them based on the [[hook]] config and the persisted state file.

State

Per-hook outcomes are stored in $DOTFILES/.yui/state.json:

{
  "version": 1,
  "hooks": {
    "install-tools": {
      "last_run_at": "2026-04-29T08:30:00+09:00[Asia/Tokyo]",
      "last_content_hash": "sha256:abc123..."
    }
  }
}

last_run_at is filled on every successful run; last_content_hash is only filled for when_run = "onchange" hooks.

Structs

HookState

State

Enums

HookOutcome

What happened when we considered running a hook.

Functions

build_hook_context

Build a Tera context for a hook: standard template_context + the script_* vars that command / args can interpolate.

run_hook

Decide whether to run hook and run it if so. Updates state in memory on a successful run — caller is responsible for persisting (typically via state.save(source) after each Ran outcome, so a later hook failure doesn’t lose the record of the earlier success).

run_phase

Run every hook whose phase matches. Stops at the first failure (the user can investigate, fix, and re-run; we don’t want to silently keep going after a failed pre hook).

sha256_hex