dot_functions

# ---------------------------- Shell & PATH Utils ---------------------------- #

# Messages start with a verb: past tense for finished work, "Failed to <verb>"
# for failures, a participle plus … for work in progress, or an imperative hint.
# The prefix holds the only formatting colon, so detail goes in parentheses.
# Colons inside data values are fine.
log() {
  local level="$1"; shift
  local red green yellow blue gray reset

  if [[ -t 2 ]]; then
    red='\033[0;31m' green='\033[0;32m' yellow='\033[0;33m'
    blue='\033[0;34m' gray='\033[0;90m' reset='\033[0m'
  fi

  case "$level" in
    error|red)      printf "${red}Error:${reset}   %s\n" "$*" >&2 ;;
    success|green)  printf "${green}Success:${reset} %s\n" "$*" ;;
    warning|yellow) printf "${yellow}Warning:${reset} %s\n" "$*" >&2 ;;
    info|blue)      printf "${blue}Info:${reset}    %s\n" "$*" ;;
    debug)          [[ -n "${DEBUG:-}" ]] && printf "${gray}Debug:${reset}   %s\n" "$*" >&2 ;;
    *)              echo "$level" "$@" ;;
  esac
}

# This draws only on a terminal, because run:daily points stderr at a report
# file. It cuts the line to the terminal width, since a wrapped line breaks the
# redraw. Call progress:clear before any other output.
progress:bar() {
  [[ -t 2 ]] || return 0
  local done="$1" total="$2" message="$3" detail="${4:-}"
  local width=24 filled body cols="${COLUMNS:-0}"
  (( total > 0 )) || return 0
  (( cols > 0 )) || cols=80

  filled=$(( done * width / total ))
  body="${message} ${(l:filled::█:)}${(l:width-filled::░:)} ${done}/${total}${detail:+ (${detail})}"
  (( ${#body} > cols - 10 )) && body="${body[1,cols-11]}…"
  printf '\r\033[K\033[0;34mInfo:\033[0m    %s' "$body" >&2
}

progress:clear() {
  [[ -t 2 ]] && printf '\r\033[K' >&2
  return 0
}

retry() {
  local attempts="$1" delay="$2"; shift 2
  local i
  for (( i = 1; i <= attempts; i++ )); do
    if "$@"; then
      return 0
    fi
    (( i < attempts )) && sleep "$delay"
  done
  return 1
}

cmd:exists() {
  [[ $# -eq 1 ]] || {
    echo "Usage: cmd:exists <command>" >&2
    return 1
  }
  command -v "$1" &>/dev/null
}

# This is narrower than cmd:exists, which also resolves aliases. The plugin
# bundle loads before .aliases, so `command -v` would report every plugin alias
# as taken, while .aliases owns the names it sets.
alias:_taken() {
  (( ${+commands[$1]} + ${+functions[$1]} + ${+builtins[$1]} ))
}

alias:safe() {
  local name="${1%%=*}"
  if alias:_taken "$name"; then
    log warning "Skipped alias '${name}' (would shadow existing command)"
  else
    alias:_set "$1"
  fi
}

# A silent alias:safe for polyfills, where a missing command is expected
alias:fallback() {
  alias:_taken "${1%%=*}" || alias:_set "$1"
}

# Resolves the target the way zsh would at expansion time
alias:_set() {
  local -a parts=( ${(z)${1#*=}} )
  local target="${(eQ)parts[1]}"
  [[ -n "$target" ]] && ! cmd:exists "$target" \
    && log warning "Defined alias '${1%%=*}' (target '${target}' is not available)"
  alias "$1"
}

# The common-aliases plugin ships suffix aliases for Linux desktop tools, and
# the ones whose tool is missing would fail on first use
alias:prune-suffix() {
  local suffix target
  local -a parts
  for suffix in ${(k)saliases}; do
    parts=( ${(z)saliases[$suffix]} )
    target="${(eQ)parts[1]}"
    if [[ -n "$target" ]] && ! cmd:exists "$target"; then
      unalias -s -- "$suffix"
    fi
  done
}

# The plugin bundle has no alias:safe, so this is how a plugin update that
# claims a command name stays visible. Deliberate shadows such as log() appear
# too.
#
# This reads $commands. whence -p forks once per name, which takes seconds
# across every alias, and it answers from the filesystem, so the
# case-insensitive volume reports /bin/lS for the lS alias.
alias:shadows() {
  local name
  rehash
  for name in ${(ko)aliases}; do
    [[ -n "${commands[$name]}" ]] \
      && printf '%-14s %-44s %s\n' "$name" "${aliases[$name]}" "${commands[$name]}"
  done
  # Nobody types _ names, which are completion functions and plugin internals
  for name in ${(ko)functions}; do
    [[ "$name" == _* || -z "${commands[$name]}" ]] && continue
    printf '%-14s %-44s %s\n' "$name" '(function)' "${commands[$name]}"
  done
}

# The job runs detached because every caller reaches the network. In front of
# the prompt that makes the day's first shell far slower, and slower still
# offline. The next shell prints the output.
run:daily() {
  local name="$1"; shift
  local stamp="${HOME}/.cache/daily/${name}"
  local report="${stamp}.report"

  # Shells with no terminal, such as an editor capturing the login environment
  # or Claude Code's shell snapshot, would lose the only record of a failed
  # update
  [[ -t 1 && -s "$report" ]] && { cat "$report"; command rm -f "$report" }

  # A run alive past its timeout means its watchdog failed too, so this warns in
  # every terminal. It removes a stale pid file (reboot, SIGKILL, reused pid).
  # The glob qualifier avoids a fork unless a pid file is overdue.
  local pidfile="${stamp}.pid"
  local -i limit=$(( ${RUN_DAILY_TIMEOUT:-300} / 60 + 2 ))
  local -a overdue=( ${pidfile}(N.mm+${limit}) )
  if (( ${#overdue} )); then
    local pid=$(<"$pidfile")
    if [[ "$pid" == <-> ]] && kill -0 "$pid" 2>/dev/null \
        && [[ "$(ps -o command= -p "$pid" 2>/dev/null)" == *_run:daily* ]]; then
      [[ -t 1 ]] && log warning "Detected ${name} still running after ${limit} minutes (stop it with 'kill -- -${pid}')" 2>&1
    else
      command rm -f "$pidfile"
    fi
  fi

  # `^ms-0` excludes a stamp dated in the future, which `mh-24` alone would
  # match forever. `ms+0` would also reject a stamp written this second.
  local -a fresh=( ${stamp}(N.mh-24^ms-0) )
  (( ${#fresh} )) && return 0

  mkdir -p "${stamp:h}"
  # Stamp before launching, so a burst of new tabs does not start one copy each.
  # The lock in _run:daily stops tabs that still pass the check together.
  touch "$stamp"

  # This starts a new session, not a background job. A `&!` job stays a process
  # group on this terminal, and the terminal stops the group (SIGTTOU, SIGTTIN)
  # when anything in it touches the tty, as antidote 2.3.0 does on every run.
  # The `$(...)` subshell then busy-loops on its stopped child at 100% CPU until
  # killed, a macOS /bin/zsh 5.9 bug fixed in 5.9.2. macOS has no setsid(1), so
  # perl calls setsid(2).
  #
  # The warning goes in the report because the GitKraken ZDOTDIR shim in Zed
  # terminals discards startup stderr.
  [[ -x /usr/bin/perl ]] || {
    log warning "Skipped ${name} (/usr/bin/perl is missing, so it cannot run detached)" 2>>"$report"
    return 0
  }
  /usr/bin/perl -MPOSIX -e 'defined(my $pid = fork) or exit 1; exit 0 if $pid;
      POSIX::setsid() > 0 or exit 1; exec @ARGV or exit 1' \
    /usr/bin/nice -n 5 /bin/zsh -fc 'source "${HOME}/.functions" && _run:daily "$@"' \
    run:daily "$name" "$report" "${RUN_DAILY_TIMEOUT:-300}" "$@" </dev/null >/dev/null 2>&1
}

# timeout(1) cannot run the callers, which are functions, so a watchdog limits
# the job. The process that hangs sits one to three levels below the job. The
# watchdog collects the process tree first, because killing a parent puts its
# children beyond pgrep. It signals the job last, because the parent kills the
# watchdog when the job dies. TERM comes first because antidote traps it to
# remove its tmpdir.
_run:daily() {
  local name="$1" report="$2" timeout="$3"; shift 3
  local job watchdog lockfd

  # A second copy would race this one on the same clones and report.new. The
  # lock ends with this shell, even on SIGKILL.
  if zmodload -F zsh/system b:zsystem 2>/dev/null; then
    : >>"${report}.lock"
    zsystem flock -t 0 -f lockfd "${report}.lock" 2>/dev/null || return 0
  fi

  # $$ leads this session's process group, so `kill -- -$$` stops the whole run
  local pidfile="${report%.report}.pid"
  print -r -- $$ >| "$pidfile"

  "$@" >| "${report}.new" 2>&1 </dev/null &
  job=$!
  ( sleep "$timeout"
    local -a tree=( $job ) level=( $job )
    while level=( ${(f)"$(pgrep -P ${(j:,:)level} 2>/dev/null)"} ); do tree=( $level $tree ); done
    # Without this line a daily timeout looks like a run with no output
    log warning "Timed out ${name} after ${timeout}s (killed it, run it by hand to see why)" 2>>"${report}.new"
    # This runs detached because the parent kills the watchdog as soon as TERM
    # arrives, and a descendant that ignores TERM would keep running
    ( sleep 5; kill -KILL $tree 2>/dev/null ) &!
    kill -TERM $tree 2>/dev/null ) & watchdog=$!
  wait $job
  kill $watchdog 2>/dev/null
  command mv -f "${report}.new" "$report"
  command rm -f "$pidfile"
}

# This prepends a directory already on PATH again, or an earlier append would
# leave it behind /usr/bin. `typeset -gU PATH path` in .zshenv drops the older
# copy.
path:add() {
  local dir
  for dir in "$@"; do
    [[ -d "$dir" ]] && export PATH="$dir:$PATH"
  done
}

path:append() {
  local dir
  for dir in "$@"; do
    [[ -d "$dir" ]] && case ":$PATH:" in
      *":$dir:"*) ;;
      *) export PATH="$PATH:$dir" ;;
    esac
  done
}

mkd() {
  mkdir -p "$@" && cd "${@[-1]}" || return
}

cdf() {
  local dir
  # `cd ""` succeeds, so this has to catch a failed osascript
  dir="$(osascript -e 'tell app "Finder" to POSIX path of (insertion location as alias)')" || return
  cd "$dir"
}

# -------------------------------- Zsh Plugins ------------------------------- #

# antidote calls a `conditional:` function with no arguments, so the tool a
# plugin needs has to be in the guard's name
local _tool
for _tool in mongocli multipass pre-commit sbt terraform; do
  functions[have:${_tool}]="cmd:exists ${_tool}"
done
unset _tool

# macOS ships a /usr/bin/rails stub, so cmd:exists always succeeds
have:rails() {
  local bin
  bin="$(whence -p rails)" || return 1
  [[ "$bin" != "/usr/bin/rails" ]]
}

# antidote never revisits a clone, so nothing else moves the plugins off their
# first commit
plugins:update() {
  local antidote="${HOMEBREW_PREFIX}/opt/antidote/share/antidote/antidote.zsh"
  local bundle="${HOME}/.cache/zsh/plugins.zsh"
  local output

  [[ -f "$antidote" && -f "${HOME}/.plugins" ]] || return 0
  source "$antidote"

  if ! output=$(antidote update 2>&1 </dev/null); then
    log warning "Failed to update zsh plugins"
    print -r -- "$output" >&2
    return 0
  fi

  # Write beside the old bundle, because a failed rebuild must leave a working
  # one
  if ! output=$(antidote bundle < "${HOME}/.plugins" 2>&1 >| "${bundle}.new"); then
    log warning "Failed to rebuild the plugin bundle (keeping the current one)"
    print -r -- "$output" >&2
    command rm -f "${bundle}.new"
    return 0
  fi
  command mv -f "${bundle}.new" "$bundle"

  log success "Updated zsh plugins"
  return 0
}

# Sourcing the bundle inside a function is safe. Only the git plugin's
# `git_version` scratch variable stops reaching the shell.
plugins:load() {
  local list="${HOME}/.plugins"
  local bundle="${HOME}/.cache/zsh/plugins.zsh"
  local antidote="${HOMEBREW_PREFIX}/opt/antidote/share/antidote/antidote.zsh"

  [[ -f "$list" ]] || return 0

  # Plugins write generated completions here on first use, so this directory has
  # to be on fpath before they load
  export ZSH_CACHE_DIR="${HOME}/.cache/oh-my-zsh"
  [[ -d "${ZSH_CACHE_DIR}/completions" ]] || mkdir -p "${ZSH_CACHE_DIR}/completions"
  fpath=("${ZSH_CACHE_DIR}/completions" $fpath)

  # Plugins read the cache as they load, so this cannot wait for .completions.
  # Without the cache the composer plugin spends about 230 ms per shell finding
  # its vendor path.
  zstyle ':completion:*' use-cache on
  zstyle ':completion:*' cache-path "${ZSH_CACHE_DIR}/zcompcache"

  # Plugins call compdef as they load, but compinit waits for .completions,
  # which finishes fpath. A second compinit would discard the first, so the calls
  # queue for .completions to replay.
  typeset -ga COMPDEF_DEFERRED=()
  (( ${+functions[compdef]} )) || \
    compdef() { COMPDEF_DEFERRED+=( "${(j: :)${(q)@}}" ) }

  if [[ ! "$bundle" -nt "$list" && -f "$antidote" ]]; then
    [[ -d "${bundle:h}" ]] || mkdir -p "${bundle:h}"
    source "$antidote"
    # `>|` truncates first, so a failed rebuild would leave an empty bundle that
    # is newer than the list. Shells started together after a list change all
    # rebuild, so each writes its own file for mv to swap in.
    if antidote bundle < "$list" >| "${bundle}.new.$$"; then
      command mv -f "${bundle}.new.$$" "$bundle"
    else
      command rm -f "${bundle}.new.$$"
    fi
  fi

  # Plugins regenerate completions in `&|` jobs on every shell. With job control
  # on, each is a background group the terminal can stop, leaving its `=(...)`
  # waiter spinning at 100% CPU (see run:daily). Only MONITOR is restored,
  # because local_options would also undo the options the plugins set.
  local monitor=$options[monitor]
  unsetopt monitor
  [[ -f "$bundle" ]] && source "$bundle"
  [[ "$monitor" == on ]] && setopt monitor
  return 0
}

# ----------------------------- Files & Archives ----------------------------- #

targz() {
  local tmpFile="${1%/}.tar"
  tar -cvf "${tmpFile}" --exclude=".DS_Store" "${@}" || return 1

  local size
  size=$(stat -f"%z" "${tmpFile}" 2>/dev/null)

  local cmd=""
  if (( size < 52428800 )) && cmd:exists zopfli; then
    cmd="zopfli"
  elif cmd:exists pigz; then
    cmd="pigz"
  else
    cmd="gzip"
  fi

  log info "Compressing .tar ($((size / 1000)) kB) using \`${cmd}\`…"
  "${cmd}" -v "${tmpFile}" || { command rm -f "${tmpFile}"; return 1; }
  [[ -f "${tmpFile}" ]] && command rm -f "${tmpFile}"

  local zippedSize
  zippedSize=$(stat -f"%z" "${tmpFile}.gz" 2>/dev/null)

  log success "Created ${tmpFile}.gz ($((zippedSize / 1000)) kB)"
}

fs() {
  if (( $# )); then
    du -sh -- "$@"
  else
    du -sh .[^.]*(N) ./*(N)
  fi
}

dataurl() {
  [[ -f "${1:-}" ]] || { log error "Failed to encode (needs an existing file, run 'dataurl <file>')"; return 1; }
  local mimeType
  mimeType=$(file -b --mime-type "$1")
  if [[ $mimeType == text/* ]]; then
    mimeType="${mimeType};charset=utf-8"
  fi
  echo "data:${mimeType};base64,$(openssl base64 -in "$1" | tr -d '\n')"
}

server() {
  local port="${1:-8000}"
  { retry 5 1 curl -fs "http://localhost:${port}/" -o /dev/null && open "http://localhost:${port}/"; } &
  python3 -m http.server "${port}"
}

gz() {
  [[ -f "${1:-}" ]] || { log error "Failed to compare (needs an existing file, run 'gz <file>')"; return 1; }
  local origsize
  origsize=$(wc -c < "$1")
  (( origsize )) || { log error "Failed to compare (${1} is empty)"; return 1; }
  local gzipsize
  gzipsize=$(gzip -c "$1" | wc -c)
  local ratio
  ratio=$(echo "$gzipsize * 100 / $origsize" | bc -l)
  printf "orig: %d bytes\n" "$origsize"
  printf "gzip: %d bytes (%2.2f%%)\n" "$gzipsize" "$ratio"
}

trec() {
  tree -aC -I "${TREE_IGNORE}" --dirsfirst "$@" | less -FRNX
}

tre() {
  tree -a -I "${TREE_IGNORE}" --dirsfirst "$@"
}

# ------------------------------ Open & Launch ------------------------------- #

o() {
  open "${@:-.}"
}

# -------------------------- Networking, TLS & DNS --------------------------- #

digga() {
  dig +nocmd "$1" any +multiline +noall +answer
}

getcertnames() {
  if [[ -z "${1}" ]]; then
    log error "Failed to read certificate names (no domain given)"
    return 1
  fi

  local domain="${1}"
  echo "Testing ${domain}…"
  echo ""

  local tmp
  tmp=$(printf 'GET / HTTP/1.0\nEOT\n' \
    | openssl s_client -connect "${domain}:443" -servername "${domain}" 2>&1)

  if [[ "${tmp}" = *"-----BEGIN CERTIFICATE-----"* ]]; then
    local certText
    certText=$(openssl x509 -text -certopt "no_aux, no_header, no_issuer, no_pubkey, \
      no_serial, no_sigdump, no_signame, no_validity, no_version" <<< "${tmp}")
    echo "Common Name:"
    echo ""
    grep "Subject:" <<< "${certText}" | sed -e "s/^.*CN=//" -e "s/\/emailAddress=.*//"
    echo ""
    echo "Subject Alternative Name(s):"
    echo ""
    grep -A 1 "Subject Alternative Name:" <<< "${certText}" \
      | sed -e "2s/DNS://g" -e "s/ //g" | tr "," "\n" | tail -n +2
    return 0
  else
    log error "Failed to find a certificate for ${domain}"
    return 1
  fi
}

dns:change() {
  if (($# < 2)); then
    echo "Usage: dns:change <network_service> <comma_separated_dns_ips>" >&2
    return 1
  fi

  local network_service="$1"
  # networksetup rejects " 8.8.8.8" from a spaced list
  local -a fields nameservers
  IFS=',' read -rA fields <<<"$2"
  local ns
  for ns in "${fields[@]}"; do
    read -r ns <<< "$ns"
    [[ -n "$ns" ]] && nameservers+=("$ns")
  done
  (( ${#nameservers} )) || { echo "dns:change: no DNS servers in '$2'" >&2; return 1; }

  sudo networksetup -setdnsservers "${network_service}" "${nameservers[@]}"
}

# ------------------------------------ SSH ----------------------------------- #

ssh:reagent() {
  local agent
  # Without (N) an unmatched glob is fatal and aborts the rest of .zshrc
  for agent in /tmp/ssh-*/agent.*(N=); do
    export SSH_AUTH_SOCK="${agent}"
    if ssh-add -l &>/dev/null; then
      log success "Found working SSH agent"
      ssh-add -l
      return 0
    fi
  done
  unset SSH_AUTH_SOCK
  log warning "Found no working SSH agent (reconnect with forwarding)"
  return 1
}

# Test the inherited socket first, because ssh:reagent's glob only matches
# sockets sshd created for a forwarded agent, never launchd's. `ssh-add -l`
# exits 2 only when it cannot reach an agent, and 1 for one holding no keys.
ssh:agent() {
  ssh-add -l &>/dev/null
  (( $? == 2 )) || return 0
  ssh:reagent &>/dev/null || eval "$(ssh-agent)" &>/dev/null
}

# --------------------------------- Secrets ---------------------------------- #

# Every read of the tokens file uses IFS=$'\t\t'. zsh treats a doubled IFS
# whitespace character as a plain separator (zshparam(1)), so empty fields
# survive the read instead of shifting the ones after them.
_SECRETS_TOKENS_FILE="${SECRETS_TOKENS_FILE}"
_SECRETS_KEYCHAIN="$HOME/Library/Keychains/${SECRETS_KEYCHAIN_NAME:-dotfiles}.keychain-db"

typeset -gA _SECRETS_FLAG_MAP=(name -l where -s kind -D comment -j)
_SECRETS_LOOKUP_FLAG="${_SECRETS_FLAG_MAP[${SECRETS_KEYCHAIN_LOOKUP_FIELD:-name}]:--l}"

# An empty SECRETS_KEYCHAIN_PASSWORD inherits the login session's unlock state,
# and a non-empty one is a master password
_secrets:ensure-keychain() {
  if [[ ! -f "$_SECRETS_KEYCHAIN" ]]; then
    local pw="${SECRETS_KEYCHAIN_PASSWORD:-}"
    security create-keychain -p "$pw" "${_SECRETS_KEYCHAIN%-db}" >/dev/null
    # Lock on sleep with no idle timeout
    security set-keychain-settings -l "$_SECRETS_KEYCHAIN"
    security unlock-keychain -p "$pw" "$_SECRETS_KEYCHAIN"
  fi
  if ! security list-keychains -d user 2>/dev/null | grep -qF -- "$_SECRETS_KEYCHAIN"; then
    # xargs would re-parse the quotes `security` prints. An apostrophe in a path
    # aborts the read and leaves `-s` setting a search list without
    # login.keychain.
    local -a paths=( ${${${(@f)"$(security list-keychains -d user)"}#*\"}%\"} )
    security list-keychains -d user -s "$_SECRETS_KEYCHAIN" "${paths[@]}"
  fi
}

_secrets:write-header() {
  printf '# id\taccount\twhere\tkind\tcomment\tpassword\n# Managed by secrets:export. Run secrets:import on a new machine to load them into the keychain\n' > "$1"
}

_secrets:ensure-tokens-file() {
  [[ -d "${_SECRETS_TOKENS_FILE:h}" ]] || mkdir -p "${_SECRETS_TOKENS_FILE:h}"
  [[ -f "$_SECRETS_TOKENS_FILE" ]] || _secrets:write-header "$_SECRETS_TOKENS_FILE"
  chmod 600 "$_SECRETS_TOKENS_FILE"
}

# dump-keychain never emits password data. It hex-encodes values holding
# non-ASCII bytes, and LC_ALL=C keeps sprintf("%c") byte-oriented while awk
# decodes them.
_secrets:entries() {
  [[ -f "$_SECRETS_KEYCHAIN" ]] || return 0
  security dump-keychain "$_SECRETS_KEYCHAIN" 2>/dev/null | LC_ALL=C awk '
    function hx(c) { return index("0123456789abcdef", c) - 1 }
    function hexdec(h,   i, out) {
      h = tolower(h); out = ""
      for (i = 1; i < length(h); i += 2)
        out = out sprintf("%c", hx(substr(h, i, 1)) * 16 + hx(substr(h, i + 1, 1)))
      return out
    }
    function val(line) {
      if (line ~ /<blob>="/) {
        sub(/^[^=]*="/, "", line); sub(/"$/, "", line); return line
      }
      if (line ~ /<blob>=0x/) {
        sub(/^[^=]*=0x/, "", line); sub(/[[:space:]].*$/, "", line)
        return hexdec(line)
      }
      return ""
    }
    function flush() {
      if (cls == "\"genp\"" && (id != "" || acct != ""))
        print id "\t" acct "\t" where "\t" kind "\t" comment
    }
    /^keychain:/            { flush(); cls = id = acct = where = kind = comment = "" }
    /^class:/               { cls = $2 }
    /^ *0x00000007 <blob>=/ { id      = val($0) }   # Label (-l)
    /^ *"acct"<blob>=/      { acct    = val($0) }
    /^ *"svce"<blob>=/      { where   = val($0) }
    /^ *"desc"<blob>=/      { kind    = val($0) }
    /^ *"icmt"<blob>=/      { comment = val($0) }
    END                     { flush() }
  ' | LC_ALL=C sort -f
}

# This uses _secrets:entries, the only parser that decodes hex values, and
# matches the lookup field so it agrees with _secrets:password
_secrets:attrs() {
  local id acct where kind comment key
  while IFS=$'\t\t' read -r id acct where kind comment; do
    case "${SECRETS_KEYCHAIN_LOOKUP_FIELD:-name}" in
      where)   key="$where" ;;
      kind)    key="$kind" ;;
      comment) key="$comment" ;;
      *)       key="$id" ;;
    esac
    [[ "$key" == "$1" && "$acct" == "$2" ]] || continue
    print -r -- "${where}"$'\t'"${kind}"$'\t'"${comment}"
    return 0
  done < <(_secrets:entries)
  return 1
}

_secrets:password() {
  security find-generic-password "$_SECRETS_LOOKUP_FLAG" "$1" -a "$2" -w "$_SECRETS_KEYCHAIN" 2>/dev/null
}

# macOS keys generic passwords by (Service, Account), not by the Label used as
# the id, so `add-generic-password -U` replaces whatever entry holds the pair
_secrets:storage-taken() {
  security find-generic-password -s "$1" -a "$2" "$_SECRETS_KEYCHAIN" >/dev/null 2>&1
}

_secrets:install() {
  local id="$1" acct="$2" where="$3" kind="$4" password="$5" comment="${6:-}"
  _secrets:ensure-keychain
  # `security -i` keeps the secret out of the process table. Its parser reads
  # the line itself, so this double quotes each value and escapes backslashes
  # first.
  local -a args=(-U -A -s "$where" -a "$acct" -l "$id" -D "$kind" -w "$password" "$_SECRETS_KEYCHAIN")
  [[ -n "$comment" ]] && args=( -j "$comment" "${args[@]}" )
  local line="add-generic-password" arg escaped
  for arg in "${args[@]}"; do
    escaped="${arg//\\/\\\\}"
    line+=" \"${escaped//\"/\\\"}\""
  done
  if ! print -r -- "$line" | security -i; then
    log error "Failed to update keychain"
    return 1
  fi
}

# macOS does not enforce a unique (id, account) pair, so this checks it
secret:set() {
  (( $# >= 4 && $# <= 5 )) || { echo "Usage: secret:set <id> <account> <where> <kind> [comment]" >&2; return 1; }
  local id="$1" account="$2" where="$3" kind="$4" comment="${5:-}" password

  if _secrets:password "$id" "$account" >/dev/null 2>&1; then
    log error "Rejected $id / $account (already exists, run secret:remove first to replace the value)"
    return 1
  fi

  if _secrets:storage-taken "$where" "$account"; then
    log error "Rejected $id / $account (another entry already holds this where and account, run secrets:list to find it)"
    return 1
  fi

  printf "Password for %s/%s: " "$id" "$account"
  read -rs password
  echo
  [[ -n "$password" ]] || { log error "Canceled (password cannot be empty)"; return 1; }

  _secrets:install "$id" "$account" "$where" "$kind" "$password" "$comment" || return 1
  log success "Added $id / $account ($kind)"
  secrets:export
}

secret:get() {
  (( $# == 2 )) || { echo "Usage: secret:get <id> <account>" >&2; return 1; }
  _secrets:password "$1" "$2" || { log error "Failed to find $1 / $2"; return 1; }
}

secret:copy() {
  (( $# == 2 )) || { echo "Usage: secret:copy <id> <account>" >&2; return 1; }
  local password snapshot ttl="${SECRETS_CLIPBOARD_TTL:-30}"

  password="$(_secrets:password "$1" "$2")" \
    || { log error "Failed to find $1 / $2"; return 1; }

  # The ConcealedType marker keeps clipboard managers such as Raycast from
  # recording the value, and CurrentHostOnly keeps it off Universal Clipboard
  printf '%s' "$password" | osascript -l JavaScript -e '
    ObjC.import("AppKit")
    const data = $.NSFileHandle.fileHandleWithStandardInput.readDataToEndOfFile
    const pb = $.NSPasteboard.generalPasteboard
    pb.prepareForNewContentsWithOptions($.NSPasteboardContentsCurrentHostOnly)
    pb.setStringForType($.NSString.alloc.initWithDataEncoding(data, $.NSUTF8StringEncoding), "public.utf8-plain-text")
    pb.setStringForType($(""), "org.nspasteboard.ConcealedType")' >/dev/null \
    || { log error "Failed to copy $1 / $2 to the clipboard"; return 1; }
  snapshot=$(printf '%s' "$password" | shasum -a 256 | awk '{print $1}')
  unset password

  ( sleep "$ttl"
    [[ "$(pbpaste 2>/dev/null | shasum -a 256 | awk '{print $1}')" == "$snapshot" ]] \
      && printf '' | pbcopy
  ) &!

  log success "Copied $1 / $2 to the clipboard (auto-clears in ${ttl}s)"
}

secret:remove() {
  (( $# == 2 )) || { echo "Usage: secret:remove <id> <account>" >&2; return 1; }
  if security delete-generic-password "$_SECRETS_LOOKUP_FLAG" "$1" -a "$2" "$_SECRETS_KEYCHAIN" >/dev/null 2>&1; then
    log success "Removed $1 / $2"
  else
    log warning "Skipped $1 / $2 (not in keychain)"
  fi
  secrets:export
}

secret:rename() {
  (( $# >= 4 && $# <= 7 )) || {
    echo "Usage: secret:rename <old_id> <old_account> <new_id> <new_account> [new_where] [new_kind] [new_comment]" >&2
    return 1
  }
  local old_id="$1" old_acct="$2" new_id="$3" new_acct="$4" password new_where new_kind new_comment
  # same_lookup means the target cannot collide under the lookup field.
  # same_storage means `add-generic-password -U` updates this item in place.
  local same_lookup=0
  [[ "$old_id" == "$new_id" && "$old_acct" == "$new_acct" ]] && same_lookup=1

  password="$(_secrets:password "$old_id" "$old_acct")" \
    || { log error "Failed to find $old_id / $old_acct"; return 1; }

  if (( ! same_lookup )) && _secrets:password "$new_id" "$new_acct" >/dev/null; then
    log error "Rejected $new_id / $new_acct (target already exists)"
    return 1
  fi

  local cur_where cur_kind cur_comment
  IFS=$'\t\t' read -r cur_where cur_kind cur_comment < <(_secrets:attrs "$old_id" "$old_acct")
  new_where="${5:-$cur_where}"
  new_kind="${6:-$cur_kind}"
  new_comment="${7:-$cur_comment}"

  local same_storage=0
  [[ "$new_where" == "$cur_where" && "$new_acct" == "$old_acct" ]] && same_storage=1

  if (( ! same_storage )) && _secrets:storage-taken "$new_where" "$new_acct"; then
    log error "Rejected $new_id / $new_acct (another entry already holds this where and account, run secrets:list to find it)"
    return 1
  fi

  _secrets:install "$new_id" "$new_acct" "$new_where" "$new_kind" "$password" "$new_comment" || return 1
  # Delete by the storage pair, because the new item may share the old Label
  if (( ! same_storage )) \
    && ! security delete-generic-password -s "$cur_where" -a "$old_acct" "$_SECRETS_KEYCHAIN" >/dev/null 2>&1; then
    log warning "Skipped removing $old_id / $old_acct (copy left behind, remove it with secret:remove)"
  fi

  log success "Renamed $old_id / $old_acct → $new_id / $new_acct ($new_kind)"
  secrets:export
}

secrets:list() {
  if [[ ! -f "$_SECRETS_KEYCHAIN" ]]; then
    log warning "Failed to find keychain ($_SECRETS_KEYCHAIN)"
    return 1
  fi

  {
    print -r -- $'ID\tACCOUNT\tKIND\tUSED BY\tWHERE'
    local id account where kind comment
    while IFS=$'\t\t' read -r id account where kind comment; do
      print -r -- "$id"$'\t'"$account"$'\t'"${kind:-(none)}"$'\t'"${comment:-(none)}"$'\t'"${where:-(none)}"
    done < <(_secrets:entries)
  } | column -t -s $'\t'
}

# This imports entries the keychain lacks and leaves stale file passwords for
# secrets:export to overwrite. A password of "placeholder" marks a stub row. It
# reports stubs and rows whose Where and Account belong to another entry, and
# never imports them.
secrets:import() {
  if [[ ! -f "$_SECRETS_TOKENS_FILE" ]]; then
    log warning "Failed to find tokens file ($_SECRETS_TOKENS_FILE)"
    return 1
  fi

  local id acct where kind comment file_pw kc_pw state total=0 drift=0 imported=0 rc
  local -a rows

  while IFS=$'\t\t' read -r id acct where kind comment file_pw; do
    [[ -z "$id" || "$id" == \#* ]] && continue
    (( ++total ))
    kc_pw="$(_secrets:password "$id" "$acct")"; rc=$?
    if (( rc == 44 )); then    # errSecItemNotFound
      if [[ -z "$file_pw" || "$file_pw" == placeholder ]]; then
        state="missing"; (( ++drift ))
      elif _secrets:storage-taken "$where" "$acct"; then
        state="conflict"; (( ++drift ))
      elif _secrets:install "$id" "$acct" "$where" "$kind" "$file_pw" "$comment"; then
        state="imported"; (( ++imported ))
      else
        state="failed"; (( ++drift ))
      fi
    elif (( rc != 0 )); then   # Locked or denied, so never write blind
      state="failed"; (( ++drift ))
    elif [[ "$file_pw" == placeholder ]]; then
      state="placeholder"; (( ++drift ))
    elif [[ "$file_pw" != "$kc_pw" ]]; then
      state="drift";       (( ++drift ))
    else
      state="ok"
    fi
    rows+=("$state"$'\t'"$id"$'\t'"$acct")
  done < "$_SECRETS_TOKENS_FILE"

  {
    print -r -- $'STATUS\tID\tACCOUNT'
    print -lr -- "${rows[@]}" | LC_ALL=C sort
  } | column -t -s $'\t'

  (( imported > 0 )) && log success "Imported $imported secret(s) into the keychain"
  if (( drift > 0 )); then
    log warning "Detected drift in $drift / $total entries (run secrets:export to sync, or secret:set to restore missing ones)"
    return 1
  fi
  log success "Synced $total / $total entries"
}

# Lets secrets:export carry a value forward when the keychain read fails
_secrets:backed-up-password() {
  [[ -f "$_SECRETS_TOKENS_FILE" ]] || return 1
  local f_id f_acct f_where f_kind f_comment f_pw
  while IFS=$'\t\t' read -r f_id f_acct f_where f_kind f_comment f_pw; do
    [[ -z "$f_id" || "$f_id" == \#* ]] && continue
    if [[ "$f_id" == "$1" && "$f_acct" == "$2" ]]; then
      print -r -- "$f_pw"
      return 0
    fi
  done < "$_SECRETS_TOKENS_FILE"
  return 1
}

# Returns zero because secrets:export is the tail call of secret:set,
# secret:remove and secret:rename, which one unreadable entry must not fail
_secrets:report-unread() {
  (( $1 )) && log warning "Carried $1 secret(s) over from the previous backup (failed to read them)"
  (( $2 )) && log error "Dropped $2 secret(s) from the backup (failed to read, with no backed-up value to keep)"
  return 0
}

secrets:export() {
  _secrets:ensure-tokens-file

  local tmp id account where kind comment password prior count=0 kept=0 dropped=0
  tmp="$(mktemp)"
  trap "command rm -f ${(q)tmp}" EXIT

  _secrets:write-header "$tmp"
  while IFS=$'\t\t' read -r id account where kind comment; do
    # (Service, Account) is unique, so this finds the entry under any lookup
    # field
    if password="$(security find-generic-password -s "$where" -a "$account" -w "$_SECRETS_KEYCHAIN" 2>/dev/null)"; then
      print -r -- "${id}"$'\t'"${account}"$'\t'"${where}"$'\t'"${kind}"$'\t'"${comment}"$'\t'"${password}" >> "$tmp"
      (( ++count ))
    # An item added outside secret:set has no -A ACL, so a denied prompt fails
    # this read alone
    elif prior="$(_secrets:backed-up-password "$id" "$account")" && [[ -n "$prior" ]]; then
      print -r -- "${id}"$'\t'"${account}"$'\t'"${where}"$'\t'"${kind}"$'\t'"${comment}"$'\t'"${prior}" >> "$tmp"
      (( ++kept ))
      log warning "Kept the backed-up value for $id / $account (failed to read password)"
    else
      (( ++dropped ))
      log error "Dropped $id / $account from the backup (failed to read password, no backed-up value to keep)"
    fi
  done < <(_secrets:entries)

  # A fresh machine's iCloud backup can sync down after bootstrap has already
  # run
  if (( count == 0 )) && grep -qvE '^[[:space:]]*#|^[[:space:]]*$' "$_SECRETS_TOKENS_FILE"; then
    command rm -f "$tmp"
    trap - EXIT
    log error "Refused to overwrite populated tokens file from an empty keychain (run secrets:import first)"
    return 1
  fi

  while IFS=$'\t\t' read -r id account; do
    [[ -n "$id" ]] && log warning "Dropped $id / $account (no longer in keychain)"
  done < <(comm -23 \
    <(awk -F'\t' '!/^[[:space:]]*#/ && NF>=2 {print $1 "\t" $2}' "$_SECRETS_TOKENS_FILE" | sort) \
    <(awk -F'\t' '!/^[[:space:]]*#/ && NF>=2 {print $1 "\t" $2}' "$tmp" | sort))

  # Skipping the write means iCloud only re-uploads on a real update
  if cmp -s "$tmp" "$_SECRETS_TOKENS_FILE"; then
    command rm -f "$tmp"
    trap - EXIT
    _secrets:report-unread "$kept" "$dropped"
    log success "Verified $count secret(s) already in sync"
    return 0
  fi

  if ! command mv "$tmp" "$_SECRETS_TOKENS_FILE"; then
    log error "Failed to write the tokens file (${_SECRETS_TOKENS_FILE})"
    return 1
  fi
  trap - EXIT
  _secrets:report-unread "$kept" "$dropped"
  log success "Exported $count secret(s) to iCloud Drive"
}

# ----------------------- macOS System Tweaks & Utilities -------------------- #

# A Focus mode hides runaway-watch's notification, so every new terminal repeats
# it. A list older than ten minutes means the agent stopped, and `^ms-0`
# excludes one dated in the future.
runaway:alerts() {
  local alerts="${XDG_CACHE_HOME:-$HOME/.cache}/runaway-watch/alerts"
  [[ -t 1 ]] || return 0
  local -a current=( ${alerts}(N.L+0mm-10^ms-0) )
  (( ${#current} )) || return 0
  log warning "Detected runaway processes (details with runaway-watch status)" 2>&1
  print -r -- "$(<"$alerts")"
}

# This uses sudo_local because every macOS update replaces /etc/pam.d/sudo
sudo:touch-id() {
  local file='/etc/pam.d/sudo_local'
  local line='auth       sufficient     pam_tid.so'

  if [[ ! -f "${file}.template" ]]; then
    log error "Failed to find ${file}.template (needs macOS 14 or newer)"
    return 1
  fi

  if [[ -f "$file" ]] && sudo grep -qE '^[^#]*pam_tid\.so' "$file"; then
    log info "Skipped pam_tid line (already present in ${file})"
    return 0
  fi

  log info "Enabling Touch ID for sudo (${file})…"
  if ! print -r -- "$line" | sudo tee -a "$file" >/dev/null; then
    log error "Failed to write ${file}"
    return 1
  fi
  sudo chmod 0444 "$file"

  log success "Enabled Touch ID for sudo"
}

# On macOS 26 this only unhides "App Store and known developers" in Privacy &
# Security, which still has to be selected there
gatekeeper:disable() {
  sudo spctl --global-disable
}

gatekeeper:enable() {
  sudo spctl --global-enable
}

hostname:get() {
  scutil --get ComputerName
}

hostname:set() {
  if [[ $# -ne 1 ]]; then
    echo "Usage: hostname:set <new_hostname>" >&2
    return 1
  fi

  local new_hostname="$1"

  # LocalHostName is the Bonjour name, so scutil rejects anything but letters,
  # digits and hyphens, including the default_hostname of "void(0)"
  local local_hostname="${new_hostname//[^a-zA-Z0-9-]/-}"
  while [[ "$local_hostname" == *--* ]]; do
    local_hostname="${local_hostname//--/-}"
  done
  local_hostname="${local_hostname#-}"
  local_hostname="${local_hostname%-}"

  if [[ -z "$local_hostname" ]]; then
    log error "Failed to derive a local host name from \"$new_hostname\""
    return 1
  fi

  sudo scutil --set ComputerName "$new_hostname" \
    && sudo scutil --set HostName "$new_hostname" \
    && sudo scutil --set LocalHostName "$local_hostname" \
    || { log error "Failed to set hostname \"$new_hostname\""; return 1; }

  if [[ "$local_hostname" != "$new_hostname" ]]; then
    log info "Set the local host name to \"$local_hostname\" (Bonjour names allow only letters, digits and hyphens)"
  fi
  log success "Set hostname \"$new_hostname\" (restart may be required)"
}

hostname:reset() {
  hostname:set "${DEFAULT_HOSTNAME}"
}

dock:reset() {
  defaults delete com.apple.dock
  killall Dock
  sleep 5

  local -a apps
  IFS=',' read -rA apps <<< "${DOCK_APPS:-}"
  local app
  for app in "${apps[@]}"; do
    app="$(printf '%s' "$app" | xargs)"
    [[ -z "$app" ]] && continue
    defaults write com.apple.dock persistent-apps -array-add "<dict><key>tile-data</key><dict><key>file-data</key><dict><key>_CFURLString</key><string>/Applications/${app}.app</string><key>_CFURLStringType</key><integer>0</integer></dict></dict></dict>"
  done

  defaults write com.apple.dock mineffect -string "scale"
  defaults write com.apple.dock minimize-to-application -bool true
  defaults write com.apple.dock launchanim -bool false
  defaults write com.apple.dock show-recents -bool false
  defaults write com.apple.dock expose-group-apps -bool true

  killall Dock
}

system:setup() {
  gatekeeper:disable
  hostname:reset
  sudo:touch-id
}

system:shutdown() {
  sudo shutdown -h now
}

system:restart() {
  sudo shutdown -r now
}

system:sleep() {
  sudo shutdown -s now
}

# ---------------------------------- Docker ---------------------------------- #

# This ignores failures because stop, rm and rmi often race each other
_docker:bulk() {
  local cmd="$1" ids="$2"
  [[ -n "$ids" ]] || return 0
  print -r -- "$ids" | xargs docker "$cmd" 2>/dev/null || true
}

# An optional extended regex keeps matching IDs, container names and image
# repositories. Extra arguments join into one pattern rather than acting as
# alternatives.
docker:cleanup() {
  docker info &>/dev/null || {
    log error "Failed to reach the Docker daemon (start Docker Desktop and retry)"
    return 1
  }

  local containers images
  if (( $# == 0 )); then
    containers="$(docker ps -aq 2>/dev/null)"   || true
    images="$(docker images -q 2>/dev/null)"    || true
  else
    local exclude="$*"
    containers="$(docker ps -a --format '{{.ID}} {{.Names}}'      2>/dev/null | grep -vE "($exclude)" | awk '{print $1}')" || true
    images="$(docker images   --format '{{.ID}} {{.Repository}}'  2>/dev/null | grep -vE "($exclude)" | awk '{print $1}')" || true
  fi
  _docker:bulk stop "$containers"
  _docker:bulk rm   "$containers"
  _docker:bulk rmi  "$images"
}

# -------------------------------- Toolchain --------------------------------- #

# Not `mise upgrade --bump`, which would rewrite the chezmoi-tracked config. -C
# keeps this unattended run from installing the toolchain of the project the
# shell started in.
mise:update() {
  local output

  # A captured upgrade logs every tool at `info`, while `-q` also drops warnings
  # about held-back releases and unfetchable version lists, which still exit 0.
  # Any other spelling of `warn` falls back to `info` without an error, and
  # `--log-level` rejects it. The commands that register a bumped JDK are `info`
  # too, so run the upgrade by hand to see them.
  if ! output=$(MISE_LOG_LEVEL=warn mise -C "$HOME" upgrade 2>&1 </dev/null); then
    log warning "Failed to update mise-managed tools"
    print -r -- "$output" >&2
    return 0
  fi

  [[ -n "$output" ]] && print -r -- "$output"

  # The `&&` above leaves status 1 on the common no-op path
  return 0
}

brew:check() {
  local deprecated outdated

  deprecated=$(brew info --installed --json=v2 2>/dev/null \
    | jq -r '(.formulae[], .casks[]) | select(.deprecated or .disabled)
      | "  \(.token // .name) (\(.deprecation_reason // .disable_reason // "unknown"))"' 2>/dev/null)

  [[ -n "$deprecated" ]] && { log warning "Detected deprecated Homebrew packages"; echo "$deprecated"; }

  outdated=$(brew outdated --quiet 2>/dev/null)
  [[ -n "$outdated" ]] || return 0

  local -a outdated_lines=( ${(f)outdated} )
  log info "Detected ${#outdated_lines} outdated Homebrew package(s) (run 'brew upgrade' to update)"
}

# `brew bundle dump` runs `npm ls -g` against the first npm on PATH, which under
# mise is not Homebrew's, so without --no-npm it records that node's global
# packages
brew:dump() {
  cmd:exists brew || { log error "Failed to find brew"; return 1; }
  cmd:exists chezmoi || { log error "Failed to find chezmoi"; return 1; }

  local source_dir brewfile
  source_dir="$(chezmoi source-path)" || return 1
  brewfile="${source_dir}/Brewfile"

  if brew bundle dump --file="$brewfile" --force --no-npm; then
    log success "Dumped Homebrew packages to ${brewfile:t}"
  else
    log error "Failed to dump Homebrew packages"
    return 1
  fi
}

# Zed has no CLI to export the list, so it comes from the index Zed maintains
# itself
zed:dump() {
  cmd:exists jq || { log error "Failed to find jq"; return 1; }
  cmd:exists chezmoi || { log error "Failed to find chezmoi"; return 1; }

  local index="${HOME}/Library/Application Support/Zed/extensions/index.json"
  [[ -r "$index" ]] || { log error "Failed to read Zed extension index (${index})"; return 1; }

  local source_dir target
  source_dir="$(chezmoi source-path)" || return 1
  target="${source_dir}/.chezmoidata/zed.toml"
  mkdir -p "${target:h}" || return 1

  # Read the list outside the redirect below, where a jq failure would overwrite
  # a good list and still report success
  local -a entries
  entries=( ${(f)"$(jq -r '.extensions | keys | .[] | "  \"\(.)\","' "$index")"} ) || {
    log error "Failed to parse Zed extension index (${index})"
    return 1
  }

  # The guard is there because `print -rl` on an empty array emits a blank line
  {
    print -r -- "# Zed extensions installed on this machine, rendered into"
    print -r -- "# auto_install_extensions by dot_config/zed/private_settings.json.tmpl."
    print -r -- "# Regenerate with zed:dump after installing or removing an extension."
    print -r -- "zed_extensions = ["
    (( ${#entries} )) && print -rl -- "${entries[@]}"
    print -r -- "]"
  } > "$target" || { log error "Failed to write ${target:t}"; return 1; }

  log success "Dumped ${#entries} Zed extension(s) to ${target:t}"
}

# ---------------------------------- Skills ---------------------------------- #

skills:sync() {
  cmd:exists yq || { log error "Failed to find yq"; return 1; }
  cmd:exists chezmoi || { log error "Failed to find chezmoi"; return 1; }

  # Declare these up front, because a bare `local x` in a loop echoes a variable
  # that has a value. The =~ tests below set MATCH and the related names.
  local source_dir inventory target owner json rows rec name url repo file dir entry
  local MATCH MBEGIN MEND
  local -i i=0 page pages
  local -a owners records entries skipped match mbegin mend
  local -A claimed taken

  source_dir="$(chezmoi source-path)" || return 1
  inventory="${source_dir}/.chezmoidata/skills.toml"
  target="${source_dir}/.chezmoidata/skills-owners.toml"

  # Read the file directly, not chezmoi's merged data, so a broken generated
  # file cannot stop the sync that rewrites it
  owners=( ${(f)"$(yq -p toml -oy '.agent_skill_owners[]' "$inventory")"} ) || return 1
  (( ${#owners} )) || { log error "Failed to read agent_skill_owners from ${inventory:t}"; return 1; }

  # Hand-written entries win, so a deliberate choice of source survives a sync
  for name in ${(f)"$(yq -p toml -oy '.agent_skills | keys | .[]' "$inventory")"}; do
    claimed[$name]=1
  done

  # `yq -e` fails an empty list, because an owner with no skills is probably a
  # typo
  for owner in "${owners[@]}"; do
    progress:bar $(( i++ )) ${#owners} "Fetching the skilld registry…" "$owner"
    page=1
    while :; do
      json="$(curl -fsSL --max-time 60 "https://skilld.dev/api/skills?owner=${owner}&page=${page}")" \
        && rows="$(print -r -- "$json" | yq -e -p json -o tsv '.items[] | [.name, .skillFileUrl]')" \
        && pages="$(print -r -- "$json" | yq -p json '.pages')" || {
        progress:clear
        log error "Failed to read the skilld registry for ${owner}"
        return 1
      }
      records+=( ${(f)rows} )
      (( page++ < pages )) || break
    done
  done
  progress:clear

  for rec in "${records[@]}"; do
    name="${rec%%$'\t'*}"
    url="${rec#*$'\t'}"
    [[ -n "$name" && "$url" == https://github.com/* ]] || continue
    if [[ -n "${claimed[$name]:-}" ]]; then
      skipped+=( "$name" )
      continue
    fi

    # The path is percent encoded, so @scope arrives as %40scope and would match
    # nothing
    repo="${${url#https://github.com/}%%/blob/*}"
    file="${${url#https://github.com/}#*/blob/}"
    file="${file#*/}"
    printf -v file '%b' "${file//\%/\\x}"
    dir="${file%/*}"
    [[ "$dir" == "$file" ]] && dir=""

    # These become a TOML key, a directory and shell arguments, so anything
    # outside the patterns is refused rather than escaped. The first owner keeps
    # a contested name.
    if [[ ! "$name" =~ '^[a-z0-9]+(-[a-z0-9]+)*$' \
      || ! "$repo" =~ '^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$' \
      || ( -n "$dir" && ! "$dir" =~ '^[A-Za-z0-9._@+-]+(/[A-Za-z0-9._@+-]+)*$' ) \
      || "/${dir}/" == */../* ]]; then
      log warning "Skipped ${name} from ${repo} (not a valid skill name or path)"
      continue
    fi
    if [[ -n "${taken[$name]:-}" ]]; then
      log warning "Skipped ${name} from ${repo} (${taken[$name]} already provides it, name one in ${inventory:t} to choose)"
      continue
    fi

    entry="[agent_skills.${name}]"$'\n'"repo = \"${repo}\""
    [[ -n "$dir" ]] && entry+=$'\n'"path = \"${dir}\""
    entries+=( "${name}"$'\t'"${entry}" )
    taken[$name]="$repo"
  done

  (( ${#entries} )) || { log error "Failed to resolve any skill for the configured owners"; return 1; }
  entries=( ${(o)entries} )

  {
    print -r -- "# Agent Skills belonging to the people listed in agent_skill_owners, resolved"
    print -r -- "# from the skilld.dev registry. GENERATED FILE: every entry here is rewritten by"
    print -r -- "# \`skills:sync\`, so edit the owner list in .chezmoidata/skills.toml instead, or"
    print -r -- "# name the skill there to override what the registry offers."
    print -r -- ""
    for rec in "${entries[@]}"; do
      print -r -- "${rec#*$'\t'}"
      print -r -- ""
    done
  } > "${target}.new" || { log error "Failed to write ${target:t}"; return 1; }
  command mv -f "${target}.new" "$target" || return 1

  log success "Resolved ${#entries} skill(s) from ${#owners} owner(s) into ${target:t}"
  if (( ${#skipped} )); then
    skipped=( ${(ou)skipped} )
    log info "Kept the named entry for ${(j:, :)skipped} rather than the registry copy"
  fi
  log info "Review the diff, then run chezmoi apply"
  return 0
}

# ------------------------------- Claude Code -------------------------------- #

# Helpers are claude:_* with no globals, because Claude Code's shell snapshot
# drops functions named _* and plain variables, and these have to work from its
# Bash tool.
#
# Claude Code keys the keychain item on this exact string, so a trailing slash
# or a path through a symlink would be a different login. The name check also
# keeps claude:remove inside ~/.claude-accounts.
claude:_path() {
  if [[ -z "$1" || "$1" == *[^a-z0-9-]* || "$1" == -* ]]; then
    log error "Rejected account name '$1' (use lowercase letters, digits and hyphens)"
    return 1
  fi
  print -r -- "${HOME}/.claude-accounts/$1"
}

claude:_home() {
  local home
  home="$(claude:_path "$1")" || return 1
  [[ -d "$home" ]] || { log error "Failed to find account $1 (add it with claude:add $1)"; return 1; }
  print -r -- "$home"
}

# State directories hold a .keep file because Claude Code's cleanup deletes
# empty ones, which would leave a running account on a dangling link.
#
# A real file in the way is how an account keeps its own configuration, while a
# real state directory means it works apart from the others. settings.json is
# the exception: it registers the guard hooks, the only guard under
# --dangerously-skip-permissions. Each link is one hop, because Claude Code
# replaces a second hop with a regular file.
#
# skills gets one link per entry, because skills/synced belongs to the signed-in
# account.
#
# `ln` without -f never removes a link another launch just made, so a launch
# that loses the race continues. -f only repairs a wrong link.
claude:_link-shared() {
  emulate -L zsh
  local home="$1" shared="${HOME}/.claude" entry
  local -a config=( settings.json CLAUDE.md agents commands keybindings.json loop.md output-styles rules security themes workflows )
  local -a state=( agent-memory file-history memory paste-cache plans projects session-env tasks teams uploads usage-data )
  local -a missing stale

  for entry in "${state[@]}"; do
    mkdir -p "${shared}/${entry}" && : >> "${shared}/${entry}/.keep" || return 1
  done
  : >> "${shared}/history.jsonl" || return 1

  for entry in "${config[@]}" "${state[@]}" history.jsonl; do
    [[ -e "${shared}/${entry}" ]] || continue
    [[ "${home}/${entry}" -ef "${shared}/${entry}" ]] && continue
    if [[ -e "${home}/${entry}" && ! -L "${home}/${entry}" ]]; then
      (( ${config[(Ie)$entry]} )) \
        || log warning "Detected ${home}/${entry}, which other accounts cannot see (merge it into ${shared}/${entry} and delete it)"
      continue
    fi
    ln -sn "${shared}/${entry}" "${home}/${entry}" 2>/dev/null \
      || [[ "${home}/${entry}" -ef "${shared}/${entry}" ]] \
      || ln -sfn "${shared}/${entry}" "${home}/${entry}" 2>/dev/null
  done
  [[ "${home}/settings.json" -ef "${shared}/settings.json" ]] || {
    log error "Failed to link ${home}/settings.json to ${shared}/settings.json (the guard hooks live there, run chezmoi apply or move the file away)"
    return 1
  }

  mkdir -p "${home}/skills" || return 1
  stale=( "${home}"/skills/*(N-@) )
  (( ${#stale} )) && command rm -f -- "${stale[@]}"
  for entry in "${shared}"/skills/*(N); do
    [[ "${entry:t}" == synced || -e "${home}/skills/${entry:t}" ]] || missing+=( "$entry" )
  done
  (( ${#missing} )) && ln -s "${missing[@]}" "${home}/skills/" 2>/dev/null
  return 0
}

# This has to be in the environment at launch, because CLAUDE_CONFIG_DIR in a
# settings file leaves .claude.json and the keychain item behind.
#
# ANTHROPIC_CONFIG_DIR moves the Console login store, which CLAUDE_CONFIG_DIR
# does not cover: a new account would pass as signed in and a logout would
# delete another account's login. BROWSER keeps sign-ins out of a default
# browser that may hold another account's claude.ai session.
#
# The unset list names what a parent shell or session passes down that would
# replace the account's login or mark this launch as a child session. `command`
# is there because exec alone would run the claude function.
claude:_run() {
  local home="$1"; shift
  (
    unset ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN ANTHROPIC_PROFILE \
      CLAUDE_CODE_OAUTH_TOKEN CLAUDE_CODE_OAUTH_REFRESH_TOKEN \
      CLAUDE_CODE_SESSION_ACCESS_TOKEN CLAUDE_CODE_ACCOUNT_UUID \
      CLAUDE_SECURESTORAGE_CONFIG_DIR CLAUDE_CODE_BRIDGE_SESSION_ID \
      CLAUDE_CODE_CHILD_SESSION CLAUDE_CODE_ENTRYPOINT CLAUDE_EFFORT CLAUDECODE
    export CLAUDE_CONFIG_DIR="$home" \
      CLAUDE_CODE_PLUGIN_CACHE_DIR="${HOME}/.claude/plugins" \
      ANTHROPIC_CONFIG_DIR="${home}/anthropic" \
      BROWSER="${HOME}/.local/bin/claude-account-browser"
    exec command "$@"
  )
}

# The extension's own login sits in its storage, so this cannot report it
claude:_chrome-state() {
  local profile="${HOME}/Library/Application Support/Google/Chrome/Profile claude-$1"
  if [[ -d "${profile}/Extensions/fcoeoabgfenejglbffodgkkbkcdhcgfn" ]]; then
    print -r -- "extension installed"
  elif [[ -d "$profile" ]]; then
    print -r -- "no extension"
  else
    print -r -- "no profile"
  fi
}

# Two processes on one conversation fork its transcript, and the next resume
# hides one side. With no session named, --continue and the picker can land on
# anything run in this directory, so any live session here counts. A session
# name counts as none named, because only an id identifies an owner.
claude:_fork-live() {
  emulate -L zsh -o extended_glob
  local resuming holder
  local -a sessions
  while (( $# )); do
    case "$1" in
      --fork-session) return 0 ;;
      -c|--continue|--from-pr|--from-pr=*) resuming=1 ;;
      --resume=*) resuming=1 sessions+=( "${${1#--resume=}:t:r}" ) ;;
      -r|--resume) resuming=1 sessions+=( "${${2:-}:t:r}" ) ;;
    esac
    shift
  done
  [[ -n "$resuming" ]] || return 0
  sessions=( ${(M)sessions:#[0-9a-f](#c8)-[0-9a-f](#c4)-[0-9a-f](#c4)-[0-9a-f](#c4)-[0-9a-f](#c12)} )
  holder="$("${HOME}/.claude/hooks/guard-live-sessions.sh" live "${PWD:A}" "${sessions[@]}" 2>/dev/null)" || return 0
  log info "Continuing in a copy (--fork-session), because ${holder} holds a session here" >&2
  print -r -- --fork-session
}

# The alias expands to this function, so plain claude cannot reopen an account's
# live session either. The function keyword keeps the alias from expanding here
# when .functions is sourced again.
function claude {
  command claude $(claude:_fork-live "$@") "$@"
}

# The alias is read at call time, because this file loads before .aliases.
# Arguments go after its flags, so a later --effort wins.
#
# --mcp-config reads only the mcpServers key and fails without one. The = form
# matters, because the flag takes several values and would swallow the arguments
# after it.
#
# From $HOME an account finds ~/.claude/settings.json as project settings and
# writes lasting project rows for every plugin into the shared registry.
claude:as() {
  (( $# >= 1 )) || { echo "Usage: claude:as <account> [claude args...]" >&2; return 1; }
  emulate -L zsh
  local home
  home="$(claude:_home "$1")" || return 1
  shift
  claude:_link-shared "$home" || return 1

  local -a flags
  if jq -e 'has("mcpServers")' "${HOME}/.claude.json" &>/dev/null; then
    flags+=( "--mcp-config=${HOME}/.claude.json" )
  fi
  [[ "$PWD" -ef "$HOME" ]] && flags+=( "--setting-sources=user,local" )
  flags+=( $(claude:_fork-live "$@") )
  claude:_run "$home" ${=aliases[claude]:-claude} "${flags[@]}" "$@"
}

claude:chrome() {
  (( $# >= 1 && $# <= 2 )) || { echo "Usage: claude:chrome <account> [url]" >&2; return 1; }
  local home
  home="$(claude:_home "$1")" || return 1
  claude:_run "$home" "${HOME}/.local/bin/claude-account-browser" "${@:2}"
}

claude:accounts() {
  emulate -L zsh
  cmd:exists jq || { log error "Failed to find jq"; return 1; }

  local name config email org uuid chrome
  local -A owner
  local -a rows warnings
  rows=( $'ACCOUNT\tEMAIL\tORGANIZATION\tCHROME' )

  for name in "(primary)" "${HOME}/.claude-accounts"/*(N/:t); do
    if [[ "$name" == "(primary)" ]]; then
      config="${HOME}/.claude.json" chrome="(any profile)"
    else
      config="${HOME}/.claude-accounts/${name}/.claude.json" chrome="$(claude:_chrome-state "$name")"
    fi
    email="" org="" uuid=""
    IFS=$'\t\t' read -r email org uuid < <(
      jq -r '.oauthAccount // {} | [.emailAddress, .organizationName, .accountUuid] | map(. // "") | @tsv' "$config" 2>/dev/null
    )
    rows+=( "${name}"$'\t'"${email:-(signed out)}"$'\t'"${org:-(none)}"$'\t'"${chrome}" )
    [[ -n "$uuid" ]] || continue
    if [[ -n "${owner[$uuid]:-}" ]]; then
      warnings+=( "$name" "${owner[$uuid]}" )
    else
      owner[$uuid]="$name"
    fi
  done

  print -rl -- "${rows[@]}" | column -t -s $'\t'
  while (( ${#warnings} )); do
    log warning "Detected ${warnings[1]} and ${warnings[2]} on one claude.ai account (sign in again with claude:as ${warnings[1]} auth login)"
    shift 2 warnings
  done
}

claude:add() {
  (( $# == 1 )) || { echo "Usage: claude:add <account>" >&2; return 1; }
  emulate -L zsh
  whence -p claude >/dev/null || { log error "Failed to find claude"; return 1; }
  local account="$1" home
  home="$(claude:_path "$account")" || return 1

  mkdir -p "$home" && chmod 700 "${home:h}" "$home" \
    || { log error "Failed to create ${home}"; return 1; }
  claude:_link-shared "$home" || return 1

  if ! claude:_run "$home" claude auth status &>/dev/null; then
    log info "Opening the sign-in page in the Chrome profile of ${account}…"
    claude:_run "$home" claude auth login \
      || { log error "Failed to sign in ${account} (run claude:add ${account} to retry)"; return 1; }
  fi

  if [[ "$(claude:_chrome-state "$account")" != "extension installed" ]]; then
    claude:chrome "$account" "https://claude.ai/chrome"
    log info "Install Claude in Chrome in the profile that just opened, then sign in to it"
  fi

  claude:accounts
  log success "Added ${account} (start it with claude:as ${account})"
}

# Signing out comes first, because the keychain item is keyed on the path and
# nothing could find it once the directory is gone
claude:remove() {
  (( $# == 1 )) || { echo "Usage: claude:remove <account>" >&2; return 1; }
  emulate -L zsh
  local account="$1" home session reply
  home="$(claude:_home "$account")" || return 1

  for session in "${home}"/sessions/<->.json(N); do
    kill -0 "${session:t:r}" 2>/dev/null || continue
    log error "Rejected removing ${account} (process ${session:t:r} still runs a session)"
    return 1
  done

  printf "Sign out %s and move %s to the Trash? [y/N] " "$account" "$home"
  read -r reply
  [[ "$reply" == [yY]* ]] || { log info "Canceled (nothing changed)"; return 1; }

  claude:_run "$home" claude auth logout >/dev/null \
    || { log error "Failed to sign out ${account} (nothing removed, run claude:remove ${account} to retry)"; return 1; }
  command trash "$home" || { log error "Failed to move ${home} to the Trash"; return 1; }
  log success "Removed ${account}"
}

# ------------------------------------ Git ----------------------------------- #

if cmd:exists git; then
  gdiff() {
    git diff --no-index --color-words "$@"
  }
fi

git:delete-branch() {
  if [[ -z "$1" ]]; then
    echo "Usage: git:delete-branch <branch>" >&2
    return 1
  fi
  git branch -d -- "$1" && git push origin :"$1"
}

gas() {
  if [[ -z "$1" ]]; then
    echo "Usage: gas <stash_index>" >&2
    return 1
  fi
  git stash apply "stash@{$1}"
}

git:rebase() {
  if [[ -z "$1" ]]; then
    echo "Usage: git:rebase <commit_count>" >&2
    return 1
  fi
  git rebase -i "HEAD~$1"
}

git:diff() {
  if [[ $# -lt 2 ]]; then
    echo "Usage: git:diff <source_branch> <target_branch> [exclude_pattern]" >&2
    return 1
  fi

  local source_branch="$1"
  local target_branch="$2"
  local exclude_pattern="$3"

  local diff_args=("$source_branch...$target_branch")
  [[ -n "$exclude_pattern" ]] && diff_args+=(-- ":!$exclude_pattern")

  # List the files first, so a bad revision leaves the clipboard alone
  local -a files
  files=( ${(f)"$(git diff --name-only "${diff_args[@]}")"} ) || {
    log error "Failed to list changed files (check '${source_branch}' and '${target_branch}' both exist)"
    return 1
  }

  # pbcopy with nothing on stdin clears the clipboard
  if (( ! ${#files} )); then
    log info "Found no differing files between '${source_branch}' and '${target_branch}'"
    return 0
  fi

  local file
  for file in "${files[@]}"; do
    printf '\n%s:\n\n' "$file"
    git show "$target_branch:$file"
  done | pbcopy

  log success "Copied changed file contents to the clipboard"
}

# --------------------------------- Chezmoi ---------------------------------- #

chezmoi:cleanup() {
  if cmd:exists compaudit; then
    # xargs would split a directory name that holds a space
    local -a dirs=( ${(f)"$(compaudit 2>/dev/null)"} )
    if (( ${#dirs} )); then
      if chmod g-w "${dirs[@]}" 2>/dev/null; then
        log success "Fixed insecure zsh completion directories"
      else
        log warning "Failed to fix some insecure zsh completion directories (run 'compaudit' to list them)"
      fi
    fi
  fi

  local gpg_locks
  gpg_locks=("$HOME"/.gnupg/public-keys.d/pubring.db*.lock(N))
  if (( ${#gpg_locks[@]} )); then
    command rm -f "${gpg_locks[@]}"
    log success "Removed ${#gpg_locks[@]} stale GnuPG lock file(s)"
  fi
}

chezmoi:sync() {
  cmd:exists chezmoi || { log error "Failed to find chezmoi"; return 1; }

  local home_dir="${HOME}"
  local updated=0
  local skipped=0
  local src tmp rel target

  while IFS= read -r target; do
    src="$(chezmoi source-path "$target" 2>/dev/null)" || continue

    [[ "$src" != *.tmpl ]] && continue
    [[ "$src" == *".chezmoi"* || "$src" == *"chezmoiscripts"* ]] && continue
    [[ ! -f "$target" ]] && continue

    # The path is baked into the trap, because an EXIT trap runs after locals
    # are popped
    tmp="$(mktemp)"
    trap "command rm -f ${(q)tmp}" EXIT
    sed "s|${home_dir}|{{ .chezmoi.homeDir }}|g" "$target" > "$tmp"

    if command diff -q "$src" "$tmp" >/dev/null 2>&1; then
      command rm -f "$tmp"
      continue
    fi

    rel="${target#"$home_dir"/}"

    # Template syntax beyond .chezmoi.homeDir needs a human
    if sed 's/{{[^}]*\.chezmoi\.homeDir[^}]*}}//g' "$src" | grep -q '{{'; then
      log warning "Skipped ${rel} (has secrets/variables, use \`chezmoi merge ${target}\`)"
      (( skipped++ ))
      command rm -f "$tmp"
      continue
    fi

    cp "$tmp" "$src"
    command rm -f "$tmp"
    log success "Synced ${rel}"
    (( updated++ ))
  done < <(chezmoi managed --include=files --path-style=absolute)

  if (( updated + skipped == 0 )); then
    log info "Verified all template-managed files already in sync"
  else
    (( updated > 0 )) && log info "Synced ${updated} file(s) back to source"
    (( skipped > 0 )) && log info "Skipped ${skipped} file(s) with complex templates"
  fi

  # The `&&` above leaves status 1 when nothing was skipped
  return 0
}