setup

#!/usr/bin/env bash

set -Eeuo pipefail

# Keep setup usable after nix-darwin removes /run/current-system from a shell
# whose command cache and PATH still reference that generation.
export PATH="${PATH:-}:/usr/bin:/bin:/usr/sbin:/sbin"
# Every Nix operation in this script is flake-based. Do not inherit an older
# nix-darwin generation's channel-backed NIX_PATH during the switch that
# replaces it.
export NIX_PATH="nixpkgs=flake:nixpkgs"
hash -r

resolve_script_path() {
  local source="${BASH_SOURCE[0]}"
  local directory target

  if [[ "${source}" != */* ]]; then
    source="$(command -v -- "${source}")"
  fi

  while [[ -L "${source}" ]]; do
    directory="$(cd -P -- "$(dirname -- "${source}")" && pwd)"
    target="$(readlink "${source}")"
    if [[ "${target}" == /* ]]; then
      source="${target}"
    else
      source="${directory}/${target}"
    fi
  done

  directory="$(cd -P -- "$(dirname -- "${source}")" && pwd)"
  printf '%s/%s\n' "${directory}" "$(basename -- "${source}")"
}

SETUP_PATH="$(resolve_script_path)"
readonly SETUP_PATH
REPO_ROOT="$(dirname -- "${SETUP_PATH}")"
readonly REPO_ROOT
readonly FLAKE_DIR="${REPO_ROOT}/nix"
readonly NIX_INSTALL_URL="https://nixos.org/nix/install"
readonly HOMEBREW_INSTALL_URL="https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh"
readonly SECRETS_REMOTE="ssh://git@github.com/randy1burrell/secrets.git"
readonly OPENPGP_ENCRYPTION_RECIPIENTS_FILE="${GNUPGHOME:-${HOME}/.gnupg}/openpgp-encryption-recipients"
readonly YUBIKEY_STATE_ROOT="${XDG_STATE_HOME:-${HOME}/.local/state}/dotfiles/yubikeys"

info() {
  printf '\033[1;34m==>\033[0m %s\n' "$*"
}

fail() {
  printf '\033[1;31merror:\033[0m %s\n' "$*" >&2
  exit 1
}

warn() {
  printf '\033[1;33mwarning:\033[0m %s\n' "$*" >&2
}

usage() {
  printf 'Usage: %s [action] [-- app-arguments...]\n\n' "${BASH_SOURCE[0]}"
  cat <<'EOF'
Run without an action to open the interactive menu.
The repository may live anywhere. Setup resolves the flake relative to this
script, regardless of the current working directory or a symlink used to run it.

System actions:
  switch       Build and activate this machine's configuration
  build        Build without activating the configuration
  check        Evaluate without building the configuration
  apply        Personalize the configuration for a machine
  apt          Install and upgrade declared Ubuntu APT packages
  snaps        Install and refresh declared Ubuntu Snap packages
  github-user  Show or change the saved GitHub username
  github-ssh-key
               Register the connected YubiKey's OpenPGP SSH key with GitHub
  doctor       Validate scripts, Nix, Emacs, GnuPG, and GitHub SSH readiness
  clean        Remove old system generations and reclaim space
  install-nix  Install upstream Nix, or replace an installer-managed Nix
  update-secrets  Encrypt and push local secrets plus a durable ~/.ssh archive
  pull-secrets    Pull, validate, back up, and restore encrypted SSH secrets
  refresh-secrets-lock
                  Refresh only the private secrets input in flake.lock

Key and GPG actions:
  gpg          Start and verify the GPG-backed SSH agent
  cache-gpg-pin
               Let one connected YubiKey retain its signature PIN until removal
  check-keys   Verify the SSH/Agenix files and GPG agent
  copy-keys    Copy keys from a mounted drive after starting GPG
  create-keys  Create SSH/Agenix keys after starting GPG
  yubikey-login
               Enable local computer login with a YubiKey PIN
  yubikey-agenix
               Provision a YubiKey for hardware-backed Agenix encryption
  yubikey-setup
               Provision one YubiKey for PINs, keys, login, SSH, and Agenix

Environment:
  GITHUB_USER  Supply the GitHub username for an unattended first run.
  SYSTEM_CONFIG  Override the flake configuration name selected from the
                 current CPU architecture.
  DOTFILES_NIXOS_HOSTNAME
                 Override the detected NixOS hostname.
  DOTFILES_NIXOS_DISK
                 Override the detected NixOS root disk (for example /dev/nvme0n1).
  KEYS_MOUNT_PATH  Select the mounted key directory for copy-keys.
  SECRETS_UPDATE_IDENTITY
                 Use a specific SSH private key while refreshing secrets.
  SECRETS_SSH_IDENTITY
                 Use a specific SSH private key for secrets push or pull.
  AGENIX_IDENTITY_PATH
                 Override ~/.ssh/id_ed25519_agenix for encryption/decryption.
  AGE_YUBIKEY_IDENTITY_PATH
                 Override ~/.config/age/yubikey-identities.txt.
  AGE_YUBIKEY_RECIPIENTS_PATH
                 Override ~/.config/age/yubikey-recipients.txt.
  SECRETS_CONFIRM=yes
                 Allow a non-interactive secrets push.
  GPG_PIN_CACHE_CONFIRM=yes
                 Confirm a non-interactive YubiKey signature-policy change.
EOF
}

github_username_path() {
  printf '%s/dotfiles/github-user\n' "${XDG_CONFIG_HOME:-${HOME}/.config}"
}

validate_github_username() {
  local username="$1"

  [[ ${#username} -ge 1 && ${#username} -le 39 ]] || return 1
  [[ "${username}" =~ ^[A-Za-z0-9]+(-[A-Za-z0-9]+)*$ ]]
}

save_github_username() {
  local username="$1" destination directory temporary

  validate_github_username "${username}" || \
    fail "GitHub usernames must be 1-39 characters and contain only letters, numbers, or single hyphens that are not first or last."

  destination="$(github_username_path)"
  directory="$(dirname -- "${destination}")"

  (
    umask 077
    mkdir -p -- "${directory}"
    temporary="$(mktemp "${directory}/github-user.XXXXXX")"
    printf '%s\n' "${username}" > "${temporary}"
    mv -f -- "${temporary}" "${destination}"
  ) || fail "Could not save the GitHub username to ${destination}."
}

read_saved_github_username() {
  local destination username
  destination="$(github_username_path)"

  [[ -r "${destination}" ]] || return 1
  IFS= read -r username < "${destination}" || true
  [[ -n "${username}" ]] || return 1
  printf '%s\n' "${username}"
}

configure_github_username() {
  local username="" saved_username=""

  saved_username="$(read_saved_github_username || true)"
  username="${saved_username:-${GITHUB_USER:-}}"

  if [[ -z "${username}" ]]; then
    [[ -t 0 ]] || \
      fail "No GitHub username is saved. Run ${SETUP_PATH} github-user USERNAME, or set GITHUB_USER for this run."
    IFS= read -r -p "GitHub username (saved for future setup runs): " username
  fi

  validate_github_username "${username}" || \
    fail "Invalid GitHub username '${username}'. Run ${SETUP_PATH} github-user to replace it."

  if [[ "${saved_username}" != "${username}" ]]; then
    save_github_username "${username}"
    info "Saved GitHub username ${username}"
  fi

  export GITHUB_USER="${username}"
  export DOTFILES_GITHUB_USER="${username}"
}

change_github_username() {
  local username="${1:-}" current=""

  [[ $# -le 1 ]] || fail "Usage: ${SETUP_PATH} github-user [USERNAME]"
  current="$(read_saved_github_username || true)"

  if [[ -z "${username}" ]]; then
    [[ -t 0 ]] || fail "Usage: ${SETUP_PATH} github-user USERNAME"
    if [[ -n "${current}" ]]; then
      IFS= read -r -p "GitHub username [${current}]: " username
      username="${username:-${current}}"
    else
      IFS= read -r -p "GitHub username: " username
    fi
  fi

  save_github_username "${username}"
  export GITHUB_USER="${username}"
  export DOTFILES_GITHUB_USER="${username}"
  info "GitHub username saved as ${username}"
  info "Run ${SETUP_PATH} switch to apply it to your shell and Git configuration"
}

load_nix() {
  hash -r
  if command -v nix >/dev/null 2>&1 && nix --version >/dev/null 2>&1; then
    return 0
  fi

  if [[ -x /nix/var/nix/profiles/default/bin/nix ]]; then
    export PATH="/nix/var/nix/profiles/default/bin:${PATH}"
    hash -r
    if nix --version >/dev/null 2>&1; then
      return 0
    fi
  fi

  local profile
  for profile in \
    /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh \
    "${HOME}/.nix-profile/etc/profile.d/nix.sh"
  do
    if [[ -r "${profile}" ]]; then
      # shellcheck disable=SC1090
      source "${profile}"
      if command -v nix >/dev/null 2>&1 && nix --version >/dev/null 2>&1; then
        return 0
      fi
    fi
  done

  return 1
}

GPG_PINENTRY_REPAIRED=0
GPG_SUITE_BIN_DIR=""
GPG_BIN=""
GPGCONF_BIN=""
GPG_AGENT_BIN=""
GPG_CONNECT_AGENT_BIN=""

select_managed_gnupg_suite() {
  local candidate fallback="" bin_directory
  local -a candidates=()

  # Home Manager owns GnuPG and its socket-activated agent. Prefer that
  # profile over Linuxbrew or the host distribution so clients, daemons, and
  # sockets always come from one release.
  if [[ "$(uname -s)" == "Darwin" ]]; then
    candidates+=(
      /run/current-system/sw/bin/gpgconf
      "${HOME}/.nix-profile/bin/gpgconf"
    )
  else
    candidates+=(
      "${HOME}/.nix-profile/bin/gpgconf"
      /run/current-system/sw/bin/gpgconf
    )
  fi

  fallback="$(command -v gpgconf 2>/dev/null || true)"
  [[ -z "${fallback}" ]] || candidates+=("${fallback}")

  for candidate in "${candidates[@]}"; do
    [[ -x "${candidate}" ]] || continue
    bin_directory="$(dirname -- "${candidate}")"
    if [[ -x "${bin_directory}/gpg" && \
          -x "${bin_directory}/gpg-agent" && \
          -x "${bin_directory}/gpg-connect-agent" ]]; then
      GPG_SUITE_BIN_DIR="${bin_directory}"
      GPG_BIN="${bin_directory}/gpg"
      GPGCONF_BIN="${candidate}"
      GPG_AGENT_BIN="${bin_directory}/gpg-agent"
      GPG_CONNECT_AGENT_BIN="${bin_directory}/gpg-connect-agent"

      # Shared setup actions are repository scripts rather than Nix app
      # wrappers, so give them the same coherent suite selected here.
      export PATH="${GPG_SUITE_BIN_DIR}:${PATH}"
      export DOTFILES_GPG="${GPG_BIN}"
      export DOTFILES_GPGCONF="${GPGCONF_BIN}"
      export DOTFILES_GPG_AGENT="${GPG_AGENT_BIN}"
      export DOTFILES_GPG_CONNECT_AGENT="${GPG_CONNECT_AGENT_BIN}"
      hash -r
      return 0
    fi
  done

  return 1
}

openpgp_encryption_fingerprints_from_colons() {
  awk -F: '
    function emit() {
      if (primary != "" && usable && encryption) print toupper(primary)
    }
    $1 == "pub" || $1 == "sec" {
      emit()
      primary = ""
      usable = ($2 !~ /[der]/)
      encryption = (usable && $12 ~ /e/)
      candidate = 0
      next
    }
    $1 == "fpr" && primary == "" {
      primary = $10
      next
    }
    $1 == "sub" || $1 == "ssb" {
      candidate = (usable && $2 !~ /[der]/ && $12 ~ /e/)
      next
    }
    $1 == "fpr" && candidate {
      encryption = 1
      candidate = 0
    }
    END { emit() }
  '
}

refresh_openpgp_encryption_recipients() {
  local public_key_bundle="${1:-}" directory temporary discovered=""
  local local_secret_recipients="" fingerprint_file

  directory="$(dirname -- "${OPENPGP_ENCRYPTION_RECIPIENTS_FILE}")"
  install -d -m 700 "${directory}"
  temporary="$(mktemp "${directory}/openpgp-encryption-recipients.XXXXXX")"

  if [[ -n "${public_key_bundle}" && -r "${public_key_bundle}" ]]; then
    discovered="$({
      LC_ALL=C "${GPG_BIN}" --batch --with-colons \
        --import-options show-only --dry-run --import "${public_key_bundle}" 2>/dev/null
    } | openpgp_encryption_fingerprints_from_colons)" || discovered=""
  fi

  # Include active encryption keys backed by secret-key stubs already known to
  # this machine. This covers a newly inserted card before its public
  # certificate has been uploaded to GitHub.
  if [[ -n "${GPG_BIN:-}" && -x "${GPG_BIN}" ]]; then
    local_secret_recipients="$({
      LC_ALL=C "${GPG_BIN}" --batch --with-colons --list-secret-keys 2>/dev/null
    } | openpgp_encryption_fingerprints_from_colons)" || local_secret_recipients=""
  fi

  {
    if [[ -r "${OPENPGP_ENCRYPTION_RECIPIENTS_FILE}" ]]; then
      cat -- "${OPENPGP_ENCRYPTION_RECIPIENTS_FILE}"
    fi
    for fingerprint_file in "${YUBIKEY_STATE_ROOT}"/*/openpgp-fingerprint.txt; do
      [[ -r "${fingerprint_file}" ]] || continue
      cat -- "${fingerprint_file}"
    done
    printf '%s\n' "${discovered}"
    printf '%s\n' "${local_secret_recipients}"
  } | awk '
    (length($0) == 40 || length($0) == 64) && $0 ~ /^[[:xdigit:]]+$/ {
      print toupper($0)
    }
  ' | sort -u > "${temporary}"

  if [[ ! -s "${temporary}" ]]; then
    rm -f -- "${temporary}"
    return 0
  fi

  if [[ -r "${OPENPGP_ENCRYPTION_RECIPIENTS_FILE}" ]] && \
     cmp -s "${temporary}" "${OPENPGP_ENCRYPTION_RECIPIENTS_FILE}"; then
    rm -f -- "${temporary}"
  else
    mv -- "${temporary}" "${OPENPGP_ENCRYPTION_RECIPIENTS_FILE}"
    info "Updated the OpenPGP encryption recipients used by Emacs"
  fi
  chmod 600 "${OPENPGP_ENCRYPTION_RECIPIENTS_FILE}"
}

sync_github_gpg_public_keys() {
  local curl_bin key_file

  # Preserve fingerprints exported by local card provisioning even when the
  # network is unavailable or a new public certificate has not been uploaded
  # to GitHub yet.
  refresh_openpgp_encryption_recipients

  [[ -n "${GITHUB_USER:-}" && -n "${GPG_BIN}" ]] || return 0
  curl_bin="$(command -v curl 2>/dev/null || true)"
  [[ -n "${curl_bin}" ]] || {
    warn "curl is unavailable; skipping GitHub OpenPGP public-key synchronization."
    return 0
  }

  key_file="$(mktemp "${TMPDIR:-/tmp}/dotfiles-github-gpg.XXXXXX")"
  if ! "${curl_bin}" --fail --silent --show-error --location \
    --proto '=https' --tlsv1.2 --connect-timeout 10 --max-time 30 \
    "https://github.com/${GITHUB_USER}.gpg" --output "${key_file}"; then
    rm -f -- "${key_file}"
    warn "Could not download ${GITHUB_USER}'s public OpenPGP certificates from GitHub; continuing with the local keyring."
    return 0
  fi

  if [[ ! -s "${key_file}" ]] || \
     ! "${GPG_BIN}" --batch --show-keys "${key_file}" >/dev/null 2>&1; then
    rm -f -- "${key_file}"
    warn "GitHub did not return a usable OpenPGP certificate for ${GITHUB_USER}."
    return 0
  fi

  if "${GPG_BIN}" --batch --import-options import-minimal \
    --import "${key_file}" >/dev/null 2>&1; then
    info "Synchronized ${GITHUB_USER}'s public OpenPGP certificates from GitHub"
    refresh_openpgp_encryption_recipients "${key_file}"
    # Importing the public certificate first lets GnuPG associate any
    # connected OpenPGP card with its non-exportable secret keys.
    "${GPG_BIN}" --batch --card-status >/dev/null 2>&1 || true
  else
    warn "Could not import ${GITHUB_USER}'s public OpenPGP certificates into the local keyring."
  fi
  rm -f -- "${key_file}"
}

ensure_linux_gpg_pinentry() {
  local gpg_directory agent_config configured_pinentry pinentry_program
  local temporary backup=""

  [[ "$(uname -s)" == "Linux" ]] || return 0

  gpg_directory="${GNUPGHOME:-${HOME}/.gnupg}"
  agent_config="${gpg_directory}/gpg-agent.conf"
  configured_pinentry="$(
    awk '$1 == "pinentry-program" { print $2; exit }' "${agent_config}" 2>/dev/null || true
  )"
  if [[ -n "${configured_pinentry}" && -x "${configured_pinentry}" ]]; then
    return 0
  fi

  if [[ -x /usr/bin/pinentry-curses ]]; then
    pinentry_program=/usr/bin/pinentry-curses
  elif pinentry_program="$(command -v pinentry-curses 2>/dev/null)" && \
    [[ -n "${pinentry_program}" ]]; then
    :
  elif pinentry_program="$(command -v pinentry 2>/dev/null)" && \
    [[ -n "${pinentry_program}" ]]; then
    :
  else
    fail "No usable Pinentry was found. Install pinentry-curses before using the YubiKey."
  fi

  mkdir -p -- "${gpg_directory}"
  chmod 700 "${gpg_directory}"
  temporary="$(mktemp "${gpg_directory}/gpg-agent.conf.XXXXXX")"
  if [[ -r "${agent_config}" ]]; then
    awk '$1 != "pinentry-program"' "${agent_config}" > "${temporary}"
  fi
  printf 'pinentry-program %s\n' "${pinentry_program}" >> "${temporary}"
  chmod 600 "${temporary}"

  if [[ -e "${agent_config}" || -L "${agent_config}" ]]; then
    backup="${agent_config}.setup-backup.$(date +%Y%m%d%H%M%S).$$"
    mv -- "${agent_config}" "${backup}" || \
      fail "Could not back up ${agent_config}."
  fi

  if ! mv -- "${temporary}" "${agent_config}"; then
    [[ -z "${backup}" ]] || mv -- "${backup}" "${agent_config}" || true
    fail "Could not install the temporary Linux Pinentry configuration."
  fi

  [[ -z "${backup}" ]] || warn "Saved the previous GPG agent configuration at ${backup}"
  info "Configured Linux Pinentry at ${pinentry_program}"
  GPG_PINENTRY_REPAIRED=1
}

prepare_gpg_ssh_agent() {
  local expected_version running_version running_dirmngr_version socket
  local ssh_executable setup_git_ssh_command

  select_managed_gnupg_suite || return 0
  ensure_linux_gpg_pinentry
  if (( GPG_PINENTRY_REPAIRED )); then
    "${GPGCONF_BIN}" --kill all >/dev/null 2>&1 || true
  fi
  "${GPGCONF_BIN}" --launch gpg-agent >/dev/null 2>&1 || return 0

  if [[ -x "${GPG_AGENT_BIN}" && -x "${GPG_CONNECT_AGENT_BIN}" ]]; then
    expected_version="$("${GPG_AGENT_BIN}" --version 2>/dev/null | awk 'NR == 1 { print $3; exit }')"
    running_version="$(
      "${GPG_CONNECT_AGENT_BIN}" 'GETINFO version' /bye 2>/dev/null |
        awk '$1 == "D" { print $2; exit }' || true
    )"

    if [[ -n "${expected_version}" && -n "${running_version}" && "${running_version}" != "${expected_version}" ]]; then
      warn "Restarting stale gpg-agent ${running_version} with managed version ${expected_version}."
      "${GPGCONF_BIN}" --kill all >/dev/null 2>&1 || true
      if [[ "$(uname -s)" == "Linux" ]] && command -v systemctl >/dev/null 2>&1; then
        # Ubuntu commonly socket-activates gpg-agent. Reload the user units
        # after a Home Manager upgrade so the next socket connection starts
        # the managed binary rather than the distribution's older service.
        systemctl --user daemon-reload >/dev/null 2>&1 || true
      fi
      "${GPGCONF_BIN}" --launch gpg-agent >/dev/null 2>&1 || \
        fail "Could not launch the managed gpg-agent ${expected_version}."
      running_version="$(
        "${GPG_CONNECT_AGENT_BIN}" 'GETINFO version' /bye 2>/dev/null |
          awk '$1 == "D" { print $2; exit }' || true
      )"
      [[ "${running_version}" == "${expected_version}" ]] || \
        fail "Expected gpg-agent ${expected_version}, but socket reports ${running_version:-unknown}."
    fi

    running_dirmngr_version="$(
      "${GPG_CONNECT_AGENT_BIN}" --dirmngr 'GETINFO version' /bye 2>/dev/null |
        awk '$1 == "D" { print $2; exit }' || true
    )"
    if [[ -n "${expected_version}" && -n "${running_dirmngr_version}" && \
          "${running_dirmngr_version}" != "${expected_version}" ]]; then
      warn "Replacing stale dirmngr ${running_dirmngr_version} with managed version ${expected_version}."
      if [[ "$(uname -s)" == "Linux" ]] && command -v systemctl >/dev/null 2>&1; then
        # Stop the distribution socket before killing the daemon. Otherwise
        # Ubuntu immediately starts /usr/bin/dirmngr again when gpgconf checks
        # the standard socket. The next Home Manager switch installs a unit
        # override that permanently points this socket at managed GnuPG.
        systemctl --user stop dirmngr.socket dirmngr.service >/dev/null 2>&1 || true
      fi
      "${GPGCONF_BIN}" --kill dirmngr >/dev/null 2>&1 || true
      "${GPGCONF_BIN}" --launch dirmngr >/dev/null 2>&1 || \
        fail "Could not launch the managed dirmngr ${expected_version}."
      running_dirmngr_version="$(
        "${GPG_CONNECT_AGENT_BIN}" --dirmngr 'GETINFO version' /bye 2>/dev/null |
          awk '$1 == "D" { print $2; exit }' || true
      )"
      [[ "${running_dirmngr_version}" == "${expected_version}" ]] || \
        fail "Expected dirmngr ${expected_version}, but socket reports ${running_dirmngr_version:-unknown}."
    fi
  fi

  sync_github_gpg_public_keys

  # Refresh the smart-card inventory before SSH asks the agent for keys. This
  # is important after changing applets or swapping among several YubiKeys.
  "${GPG_CONNECT_AGENT_BIN}" 'SCD SERIALNO --all' /bye >/dev/null 2>&1 || true

  socket="$("${GPGCONF_BIN}" --list-dirs agent-ssh-socket 2>/dev/null || true)"
  [[ -n "${socket}" ]] || return 0

  export SSH_AUTH_SOCK="${socket}"

  # Point setup's Git and Nix input fetches at gpg-agent even before the
  # generated SSH config is active. Conventional default identity files remain
  # available as migration fallbacks because IdentitiesOnly is disabled.
  if [[ -z "${GIT_SSH_COMMAND:-}" ]]; then
    ssh_executable="$(command -v ssh)"
    if [[ "$(uname -s)" == "Linux" && -x /usr/bin/ssh ]]; then
      # Ubuntu's client supports the GSSAPI options in /etc/ssh/ssh_config;
      # the standard Nixpkgs build does not.
      ssh_executable=/usr/bin/ssh
    fi
    printf -v setup_git_ssh_command \
      '%q -o IdentityAgent=%q -o IdentitiesOnly=no' \
      "${ssh_executable}" "${socket}"
    export GIT_SSH_COMMAND="${setup_git_ssh_command}"
  fi

  if [[ -t 0 ]]; then
    export GPG_TTY
    GPG_TTY="$(tty)"
    "${GPG_CONNECT_AGENT_BIN}" --quiet updatestartuptty /bye >/dev/null 2>&1 || true
  fi
}

register_github_ssh_key() (
  local authenticated_user auth_fingerprint card_status gh_bin gh_root github_keys
  local delay key_file public_key serial ssh_key title

  download_github_ssh_keys() {
    curl --fail --silent --show-error --location \
      --header 'Cache-Control: no-cache' \
      --proto '=https' --tlsv1.2 --connect-timeout 10 --max-time 30 \
      "https://github.com/${GITHUB_USER}.keys" --output "${github_keys}"
  }

  github_ssh_key_is_registered() {
    download_github_ssh_keys && \
      awk 'NF >= 2 { print $1 " " $2 }' "${github_keys}" |
        grep -Fqx -- "${ssh_key}"
  }

  command -v curl >/dev/null 2>&1 || fail "curl is required to inspect GitHub SSH keys."

  prepare_gpg_ssh_agent
  card_status="$("${GPG_BIN}" --with-colons --card-status 2>/dev/null)" || \
    fail "GnuPG could not read an OpenPGP card. Insert exactly one configured YubiKey and retry."
  serial="$(awk -F: '$1 == "serial" { print $2; exit }' <<< "${card_status}")"
  auth_fingerprint="$(awk -F: '$1 == "fpr" && NF >= 4 { print $4; exit }' <<< "${card_status}")"
  [[ -n "${serial}" && -n "${auth_fingerprint}" ]] || \
    fail "The connected YubiKey does not report an OpenPGP authentication key. Run ${SETUP_PATH} yubikey-setup first."

  public_key="$("${GPG_BIN}" --export-ssh-key "${auth_fingerprint}!" 2>/dev/null)" || \
    fail "Could not convert OpenPGP authentication key ${auth_fingerprint} to an SSH public key."
  ssh_key="$(awk 'NF >= 2 { print $1 " " $2; exit }' <<< "${public_key}")"
  [[ -n "${ssh_key}" ]] || fail "GnuPG returned an empty SSH public key."

  github_keys="$(mktemp "${TMPDIR:-/tmp}/dotfiles-github-keys.XXXXXX")"
  key_file="$(mktemp "${TMPDIR:-/tmp}/dotfiles-yubikey-ssh.XXXXXX")"
  trap 'rm -f -- "${github_keys:-}" "${key_file:-}"' EXIT
  printf '%s\n' "${public_key}" > "${key_file}"

  if github_ssh_key_is_registered; then
    info "YubiKey ${serial}'s OpenPGP authentication key is already registered with GitHub user ${GITHUB_USER}"
    return 0
  fi

  gh_bin="$(command -v gh 2>/dev/null || true)"
  if [[ -z "${gh_bin}" ]]; then
    load_nix || fail "GitHub CLI is not installed and Nix is unavailable to load it. Install gh, then retry."
    info "Loading GitHub CLI from Nix for this registration"
    gh_root="$(
      nix --extra-experimental-features 'nix-command flakes' build \
        --no-link --print-out-paths 'github:NixOS/nixpkgs/nixos-26.05#gh'
    )" || fail "Nix could not provide GitHub CLI. Check network access and retry."
    gh_bin="${gh_root}/bin/gh"
  fi

  if ! "${gh_bin}" auth status --hostname github.com >/dev/null 2>&1; then
    [[ -t 0 ]] || \
      fail "GitHub CLI is not authenticated. Run gh auth login --hostname github.com, then retry."
    info "Opening GitHub CLI authentication; sign in as ${GITHUB_USER}"
    "${gh_bin}" auth login --hostname github.com --web --skip-ssh-key \
      --scopes admin:public_key || \
      fail "GitHub CLI authentication did not complete."
  fi
  authenticated_user="$("${gh_bin}" api user --jq .login 2>/dev/null || true)"
  [[ "${authenticated_user}" == "${GITHUB_USER}" ]] || \
    fail "GitHub CLI is authenticated as ${authenticated_user:-unknown}, but setup is configured for ${GITHUB_USER}. Run gh auth switch --hostname github.com --user ${GITHUB_USER}, then retry."

  title="YubiKey ${serial} OpenPGP ($(hostname -s 2>/dev/null || hostname))"
  info "Registering YubiKey ${serial}'s OpenPGP authentication key with GitHub user ${GITHUB_USER}"
  if ! "${gh_bin}" ssh-key add "${key_file}" --type authentication --title "${title}"; then
    fail "GitHub rejected the key registration. Run gh auth refresh --hostname github.com --scopes admin:public_key, then retry."
  fi

  # Public key endpoints can lag briefly behind a successful API write. Retry
  # for a few seconds so normal propagation is not reported as a failure.
  for delay in 0 1 2 3 4; do
    (( delay == 0 )) || sleep "${delay}"
    github_ssh_key_is_registered && break
  done
  github_ssh_key_is_registered || \
    fail "GitHub accepted the request but did not publish the key for ${GITHUB_USER}. Check gh ssh-key list before retrying secrets access."

  info "GitHub SSH registration succeeded; ${SETUP_PATH} pull-secrets can now authenticate with this YubiKey"
)

prepare_darwin_nix_mountpoint() {
  local backup_path="" synthetic_tmp

  [[ "$(uname -s)" == "Darwin" ]] || return 0

  if [[ -L /nix ]]; then
    fail "/nix is a symlink to $(/usr/bin/readlink /nix). Remove the conflicting synthetic link and reboot before installing Nix."
  fi

  synthetic_tmp="$(/usr/bin/mktemp "${TMPDIR:-/tmp}/synthetic-conf.XXXXXX")"
  if [[ -e /etc/synthetic.conf ]]; then
    /usr/bin/awk '
      BEGIN { print "nix" }
      {
        normalized = $0
        sub(/\r$/, "", normalized)
        if (normalized == "nix" || normalized ~ /^nix[[:space:]]/) next
        print $0
      }
    ' /etc/synthetic.conf > "${synthetic_tmp}"
  else
    printf 'nix\n' > "${synthetic_tmp}"
  fi

  if [[ -e /etc/synthetic.conf ]] \
    && /usr/bin/cmp -s "${synthetic_tmp}" /etc/synthetic.conf
  then
    /bin/rm -f "${synthetic_tmp}"
    return 0
  fi

  info "Repairing the macOS /nix synthetic mount-point declaration"
  sudo -v || {
    /bin/rm -f "${synthetic_tmp}"
    fail "Administrator authentication failed; synthetic.conf was not changed."
  }

  sudo /bin/mkdir -p /var/backups
  if [[ -e /etc/synthetic.conf ]]; then
    backup_path="/var/backups/dotfiles-synthetic.conf-$(/bin/date +%Y%m%d-%H%M%S)-$$"
    sudo /bin/cp -p /etc/synthetic.conf "${backup_path}"
  fi
  sudo /usr/bin/install -o root -g wheel -m 0644 \
    "${synthetic_tmp}" /etc/synthetic.conf
  /bin/rm -f "${synthetic_tmp}"

  {
    /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -t || true
    /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -B || true
  } >/dev/null 2>&1

  /usr/bin/grep -q '^nix$' /etc/synthetic.conf || \
    fail "Could not create an exact nix entry in /etc/synthetic.conf."

  if [[ -n "${backup_path}" ]]; then
    info "Previous synthetic.conf saved at ${backup_path}"
  fi
}

install_upstream_nix() {
  local installer="$1" install_log install_mode status

  case "$(uname -s)" in
    Darwin)
      install_mode="--daemon"
      prepare_darwin_nix_mountpoint
      ;;
    Linux)
      if [[ -d /run/systemd/system ]]; then
        install_mode="--daemon"
      else
        install_mode="--no-daemon"
      fi
      ;;
    *)
      fail "The upstream Nix installer is unsupported on $(uname -s)."
      ;;
  esac

  if [[ "$(uname -s)" != "Darwin" ]]; then
    NIX_INSTALLER_NO_CHANNEL_ADD=1 NIX_INSTALLER_YES=1 \
      /bin/sh "${installer}" "${install_mode}"
    return $?
  fi

  install_log="$(/usr/bin/mktemp "${TMPDIR:-/tmp}/upstream-nix-install.XXXXXX")"
  if NIX_INSTALLER_NO_CHANNEL_ADD=1 NIX_INSTALLER_YES=1 \
    /bin/sh "${installer}" "${install_mode}" \
      2> >(/usr/bin/tee "${install_log}" >&2)
  then
    /bin/rm -f "${install_log}"
    return 0
  else
    status=$?
  fi

  if ! /usr/bin/grep -Fq 'failed to configure synthetic.conf' "${install_log}"; then
    /bin/rm -f "${install_log}"
    return "${status}"
  fi

  warn "The Nix installer removed the repaired synthetic entry during cleanup; restoring it and retrying once."
  /bin/rm -f "${install_log}"
  prepare_darwin_nix_mountpoint
  NIX_INSTALLER_NO_CHANNEL_ADD=1 NIX_INSTALLER_YES=1 \
    /bin/sh "${installer}" "${install_mode}"
}

install_nix() {
  command -v curl >/dev/null 2>&1 || fail "curl is required to install Nix."

  local installer
  installer="$(mktemp)"

  info "Nix is not installed; downloading the official upstream Nix installer"
  if ! curl --fail --silent --show-error --location \
    --proto '=https' --tlsv1.2 "${NIX_INSTALL_URL}" --output "${installer}"
  then
    rm -f -- "${installer}"
    fail "Could not download the Nix installer."
  fi

  if ! install_upstream_nix "${installer}"; then
    rm -f -- "${installer}"
    fail "Nix installation failed."
  fi
  rm -f -- "${installer}"

  load_nix || fail "Nix installed, but this shell could not load it. Open a new terminal and verify it with nix --version."
}

system_curl() {
  local candidate resolved

  for candidate in /usr/bin/curl /bin/curl; do
    [[ -x "${candidate}" ]] && { printf '%s\n' "${candidate}"; return 0; }
  done

  candidate="$(command -v curl 2>/dev/null || true)"
  [[ -n "${candidate}" ]] || return 1
  resolved="$(readlink -f "${candidate}" 2>/dev/null || printf '%s' "${candidate}")"
  [[ "${resolved}" != /nix/* ]] || return 1
  printf '%s\n' "${candidate}"
}

nix_darwin_remnants_present() {
  [[ -L /etc/static || -L /run/current-system \
    || -e /Library/LaunchDaemons/org.nixos.activate-system.plist \
    || -e /Library/LaunchDaemons/org.nixos.activate-agenix.plist \
    || -e /Library/LaunchDaemons/org.nixos.nix-gc.plist ]]
}

recover_upstream_nix() {
  local backup_root confirmation current_uid current_user daemon_plist profile_root
  local config_tmp synthetic_tmp target path backup_source label

  profile_root="/nix/var/nix/profiles/default"
  daemon_plist="${profile_root}/Library/LaunchDaemons/org.nixos.nix-daemon.plist"
  current_uid="$(/usr/bin/id -u)"
  current_user="$(/usr/bin/id -un)"

  [[ "$(uname -s)" == "Darwin" ]] || \
    fail "The nix-darwin recovery is available only on macOS."
  [[ -x "${profile_root}/bin/nix" \
    && -r "${profile_root}/etc/profile.d/nix-daemon.sh" \
    && -r "${daemon_plist}" ]] || \
    fail "The installer-owned upstream Nix profile is incomplete; automatic recovery was stopped."

  for path in /etc/bashrc /etc/zshenv /etc/zprofile /etc/zshrc; do
    if [[ -L "${path}" ]]; then
      target="$(/usr/bin/readlink "${path}")"
      [[ "${target}" == /etc/static/* ]] || \
        fail "Refusing to replace unexpected symlink ${path} -> ${target}."
      backup_source="${path}.before-nix-darwin"
      [[ -r "${backup_source}" ]] || \
        fail "Cannot recover ${path}; expected backup ${backup_source} is missing."
    fi
  done

  if [[ -L /etc/static ]]; then
    target="$(/usr/bin/readlink /etc/static)"
    [[ "${target}" == /nix/store/*-etc/etc ]] || \
      fail "Refusing to remove unexpected /etc/static symlink target ${target}."
  fi
  if [[ -L /run/current-system ]]; then
    target="$(/usr/bin/readlink /run/current-system)"
    [[ "${target}" == /nix/store/*-darwin-system-* ]] || \
      fail "Refusing to remove unexpected /run/current-system target ${target}."
  fi

  printf 'A usable upstream Nix profile already exists in the current store.\n'
  printf 'This recovery preserves /nix, removes verified nix-darwin services and links,\n'
  printf 'and switches the daemon and shell startup files to upstream Nix.\n'
  IFS= read -r -p "Type 'recover' to continue, or press Enter to cancel: " confirmation || true
  if [[ "${confirmation}" != "recover" ]]; then
    info "Upstream Nix recovery cancelled"
    return 0
  fi

  sudo -v || fail "Administrator authentication failed; recovery was not started."
  backup_root="/var/backups/dotfiles-upstream-nix-$(/bin/date +%Y%m%d-%H%M%S)"
  sudo /bin/mkdir -p "${backup_root}"

  backup_path() {
    local source="$1" destination="${backup_root}$1"
    if [[ -e "${source}" || -L "${source}" ]]; then
      sudo /bin/mkdir -p "$(/usr/bin/dirname "${destination}")"
      sudo /bin/mv "${source}" "${destination}"
    fi
  }

  copy_to_backup() {
    local source="$1" destination="${backup_root}$1"
    if [[ -e "${source}" || -L "${source}" ]]; then
      sudo /bin/mkdir -p "$(/usr/bin/dirname "${destination}")"
      sudo /bin/cp -pPR "${source}" "${destination}"
    fi
  }

  info "Stopping nix-darwin user services"
  for label in org.nixos.emacs org.nixos.skhd; do
    path="${HOME}/Library/LaunchAgents/${label}.plist"
    /bin/launchctl bootout "gui/${current_uid}/${label}" >/dev/null 2>&1 || true
    backup_path "${path}"
  done

  info "Removing nix-darwin system services"
  for label in org.nixos.activate-agenix org.nixos.activate-system org.nixos.nix-gc; do
    sudo /bin/launchctl bootout "system/${label}" >/dev/null 2>&1 || true
    backup_path "/Library/LaunchDaemons/${label}.plist"
  done

  if [[ -e /Library/LaunchDaemons/systems.determinate.nix-installer.nix-hook.plist ]]; then
    sudo /bin/launchctl bootout system/systems.determinate.nix-installer.nix-hook \
      >/dev/null 2>&1 || true
    backup_path /Library/LaunchDaemons/systems.determinate.nix-installer.nix-hook.plist
  fi

  info "Restoring installer-owned shell startup files"
  for path in /etc/bashrc /etc/zshenv /etc/zprofile /etc/zshrc; do
    if [[ -L "${path}" ]]; then
      backup_source="${path}.before-nix-darwin"
      backup_path "${path}"
      sudo /bin/cp -p "${backup_source}" "${path}"
    fi
  done

  for path in /etc/skhdrc /etc/terminfo /etc/pam.d/sudo_local; do
    if [[ -L "${path}" ]]; then
      target="$(/usr/bin/readlink "${path}")"
      if [[ "${target}" == /etc/static/* ]]; then
        backup_path "${path}"
      else
        fail "Refusing to remove unexpected symlink ${path} -> ${target}."
      fi
    fi
  done

  info "Installing a standalone upstream Nix configuration"
  config_tmp="$(/usr/bin/mktemp "${TMPDIR:-/tmp}/upstream-nix-conf.XXXXXX")"
  {
    printf 'build-users-group = nixbld\n'
    printf 'experimental-features = nix-command flakes\n'
    printf 'ssl-cert-file = %s/etc/ssl/certs/ca-bundle.crt\n' "${profile_root}"
    printf 'trusted-users = root @admin %s\n' "${current_user}"
  } > "${config_tmp}"
  backup_path /etc/nix/nix.conf
  sudo /bin/mkdir -p /etc/nix
  sudo /usr/bin/install -o root -g wheel -m 0644 "${config_tmp}" /etc/nix/nix.conf
  /bin/rm -f "${config_tmp}"

  if [[ -L /etc/ssl/certs/ca-certificates.crt ]]; then
    target="$(/usr/bin/readlink /etc/ssl/certs/ca-certificates.crt)"
    if [[ "${target}" == /etc/static/* ]]; then
      backup_path /etc/ssl/certs/ca-certificates.crt
      sudo /bin/ln -s \
        "${profile_root}/etc/ssl/certs/ca-bundle.crt" \
        /etc/ssl/certs/ca-certificates.crt
    fi
  fi

  if [[ -e /etc/synthetic.conf ]]; then
    synthetic_tmp="$(/usr/bin/mktemp "${TMPDIR:-/tmp}/synthetic-conf.XXXXXX")"
    /usr/bin/awk 'BEGIN { print "nix" } $0 == "nix" { next } $1 == "run" && $2 == "private/var/run" { next } { print }' \
      /etc/synthetic.conf > "${synthetic_tmp}"
    if ! /usr/bin/cmp -s "${synthetic_tmp}" /etc/synthetic.conf; then
      copy_to_backup /etc/synthetic.conf
      sudo /usr/bin/install -o root -g wheel -m 0644 \
        "${synthetic_tmp}" /etc/synthetic.conf
    fi
    /bin/rm -f "${synthetic_tmp}"
  fi

  info "Switching to the upstream Nix daemon"
  sudo /bin/launchctl bootout system/org.nixos.nix-daemon >/dev/null 2>&1 || true
  copy_to_backup /Library/LaunchDaemons/org.nixos.nix-daemon.plist
  sudo /bin/cp "${daemon_plist}" /Library/LaunchDaemons/org.nixos.nix-daemon.plist
  sudo /usr/sbin/chown root:wheel /Library/LaunchDaemons/org.nixos.nix-daemon.plist
  sudo /bin/chmod 0644 /Library/LaunchDaemons/org.nixos.nix-daemon.plist
  sudo /bin/launchctl bootstrap system /Library/LaunchDaemons/org.nixos.nix-daemon.plist
  sudo /bin/launchctl kickstart -k system/org.nixos.nix-daemon

  backup_path /Applications/Nix\ Apps
  backup_path /run/current-system
  backup_path /etc/static
  backup_path /nix/receipt.json
  backup_path /nix/nix-installer

  export PATH="${profile_root}/bin:/usr/bin:/bin:/usr/sbin:/sbin:${PATH}"
  unset __NIX_DARWIN_SET_ENVIRONMENT_DONE __ETC_PROFILE_NIX_SOURCED || true
  hash -r
  nix --version >/dev/null 2>&1 || \
    fail "Recovery completed, but the upstream Nix client did not start. Backup: ${backup_root}"
  nix store info >/dev/null 2>&1 || \
    fail "Recovery completed, but the upstream Nix daemon did not respond. Backup: ${backup_root}"

  info "Upstream Nix recovery completed; backup saved at ${backup_root}"
  warn "Open a new terminal so it no longer inherits nix-darwin environment variables."
  warn "Reboot macOS when convenient to remove the obsolete /run synthetic link."
}

reinstall_nix() {
  local current_version installer curl_command confirmation darwin_uninstaller=""

  current_version="$(nix --version 2>/dev/null || printf 'an unknown Nix version')"
  printf 'Nix is already installed: %s\n' "${current_version}"
  printf '\033[1;33mA full reinstall removes the Nix store, installed packages, and system generations.\033[0m\n'
  printf 'Your dotfiles repository is outside the Nix store and will not be removed.\n'
  printf 'nix-darwin will remain uninstalled; only upstream Nix will be installed.\n'
  IFS= read -r -p "Type 'reinstall' to continue, or press Enter to cancel: " confirmation || true

  if [[ "${confirmation}" != "reinstall" ]]; then
    info "Nix reinstall cancelled"
    return 0
  fi

  [[ -x /nix/nix-installer && -f /nix/receipt.json ]] || \
    fail "This Nix installation has no Determinate installer receipt, so setup will not remove it automatically. Follow the installer-specific uninstall instructions instead."

  curl_command="$(system_curl)" || \
    fail "A curl executable outside /nix is required before the Nix store can be removed."
  installer="$(mktemp)"

  info "Downloading the replacement installer before removing the existing Nix store"
  if ! "${curl_command}" --fail --silent --show-error --location \
    --proto '=https' --tlsv1.2 "${NIX_INSTALL_URL}" --output "${installer}"
  then
    /bin/rm -f -- "${installer}"
    fail "Could not download the replacement Nix installer. The existing installation was not changed."
  fi

  if [[ "$(uname -s)" == "Darwin" ]]; then
    if [[ -x /run/current-system/sw/bin/darwin-uninstaller ]]; then
      darwin_uninstaller="/run/current-system/sw/bin/darwin-uninstaller"
    elif command -v darwin-uninstaller >/dev/null 2>&1; then
      darwin_uninstaller="$(command -v darwin-uninstaller)"
    fi

    if [[ -n "${darwin_uninstaller}" ]]; then
      info "Temporarily uninstalling nix-darwin before removing Nix"
      if ! sudo -v; then
        /bin/rm -f -- "${installer}"
        fail "Administrator authentication failed; neither nix-darwin nor Nix was removed."
      fi

      # The user already confirmed the full reinstall above. Supplying a
      # non-terminal input prevents darwin-uninstaller from prompting twice.
      if ! sudo "${darwin_uninstaller}" </dev/null; then
        /bin/rm -f -- "${installer}"
        fail "nix-darwin uninstall failed; Nix was not removed."
      fi
    fi
  fi

  info "Uninstalling the installer-managed Nix installation"
  if ! sudo /nix/nix-installer uninstall --no-confirm; then
    /bin/rm -f -- "${installer}"
    if [[ -n "${darwin_uninstaller}" ]]; then
      fail "Nix uninstall failed after nix-darwin was removed. Nix is still installed; resolve the reported error and run ${SETUP_PATH} install-nix again."
    fi
    fail "Nix uninstall failed; reinstall was stopped."
  fi

  info "Installing a fresh upstream Nix environment"
  if ! install_upstream_nix "${installer}"; then
    /bin/rm -f -- "${installer}"
    fail "The old Nix installation was removed, but the fresh installation failed. Re-run ${BASH_SOURCE[0]} install-nix."
  fi
  /bin/rm -f -- "${installer}"

  load_nix || fail "Nix was reinstalled, but this shell could not load it. Open a new terminal and verify it with nix --version."
  info "Upstream Nix reinstallation completed; nix-darwin remains uninstalled"
}

install_or_reinstall_nix() {
  if load_nix; then
    if [[ "$(uname -s)" == "Linux" && -e /etc/NIXOS ]]; then
      info "NixOS manages Nix declaratively; rebuilding the system instead of deleting /nix"
      run_action switch
    elif [[ "$(uname -s)" == "Darwin" ]] && nix_darwin_remnants_present; then
      recover_upstream_nix
    elif [[ ! -x /nix/nix-installer || ! -f /nix/receipt.json ]]; then
      info "Upstream Nix is already installed; no replacement is necessary"
    else
      reinstall_nix
    fi
  else
    install_nix
    info "Upstream Nix installation completed"
  fi
}

system_name() {
  local kernel machine
  kernel="$(uname -s)"
  machine="$(uname -m)"

  case "${kernel}:${machine}" in
    Darwin:arm64) printf '%s\n' aarch64-darwin ;;
    Darwin:x86_64) printf '%s\n' x86_64-darwin ;;
    Linux:aarch64|Linux:arm64) printf '%s\n' aarch64-linux ;;
    Linux:x86_64) printf '%s\n' x86_64-linux ;;
    *) fail "Unsupported platform: ${kernel} ${machine}" ;;
  esac
}

darwin_configuration_name() {
  local system="$1" nixbld_gid

  nixbld_gid="$({
    /usr/bin/dscl . -read /Groups/nixbld PrimaryGroupID 2>/dev/null || true
  } | awk '$1 == "PrimaryGroupID:" { print $2; exit }')"
  if [[ -z "${nixbld_gid}" ]]; then
    nixbld_gid="$({
      /usr/bin/dscacheutil -q group -a name nixbld 2>/dev/null || true
    } | awk '$1 == "gid:" { print $2; exit }')"
  fi

  case "${nixbld_gid}" in
    30000) printf '%s\n' "${system}" ;;
    350) printf '%s-gid350\n' "${system}" ;;
    "") fail "The macOS nixbld group does not exist. Install or repair Nix before building nix-darwin." ;;
    *) fail "Unsupported nixbld group ID ${nixbld_gid}. Add a matching declarative Darwin configuration before switching." ;;
  esac
}

platform_kind() {
  case "$(uname -s)" in
    Darwin) printf '%s\n' darwin ;;
    Linux)
      if [[ -e /etc/NIXOS ]]; then
        printf '%s\n' nixos
      else
        printf '%s\n' generic-linux
      fi
      ;;
    *) fail "Unsupported operating system: $(uname -s)" ;;
  esac
}

run_nix() {
  nix --extra-experimental-features 'nix-command flakes' "$@"
}

configure_generic_linux_identity() {
  local current_uid current_user

  current_uid="$(id -u)"
  current_user="$(id -un)"

  [[ "${current_uid}" -ne 0 ]] || \
    fail "Run the standalone Home Manager configuration as your normal Ubuntu user, not with sudo."
  [[ -n "${current_user}" ]] || fail "Could not determine the current Ubuntu username."
  [[ -n "${HOME:-}" && "${HOME}" == /* && -d "${HOME}" ]] || \
    fail "HOME must be an existing absolute directory for the current Ubuntu user."

  export DOTFILES_LINUX_USER="${current_user}"
  export DOTFILES_LINUX_HOME="${HOME}"
  info "Using Ubuntu account ${DOTFILES_LINUX_USER} at ${DOTFILES_LINUX_HOME}"
}

configure_nixos_identity() {
  local current_uid current_user detected_disk="" root_source=""

  current_uid="$(id -u)"
  current_user="$(id -un)"

  [[ "${current_uid}" -ne 0 ]] || \
    fail "Run setup as your normal NixOS user, not with sudo. It will request administrator access when needed."
  [[ -n "${current_user}" ]] || fail "Could not determine the current NixOS username."
  [[ -n "${HOME:-}" && "${HOME}" == /* && -d "${HOME}" ]] || \
    fail "HOME must be an existing absolute directory for the current NixOS user."

  export DOTFILES_NIXOS_USER="${current_user}"
  export DOTFILES_NIXOS_HOME="${HOME}"
  export DOTFILES_NIXOS_HOSTNAME="${DOTFILES_NIXOS_HOSTNAME:-$(hostname -s)}"
  [[ "${DOTFILES_NIXOS_HOSTNAME}" =~ ^[[:alnum:]][[:alnum:]_-]{0,61}[[:alnum:]]$ || \
     "${DOTFILES_NIXOS_HOSTNAME}" =~ ^[[:alnum:]]$ ]] || \
    fail "Invalid NixOS hostname ${DOTFILES_NIXOS_HOSTNAME}."

  if [[ -z "${DOTFILES_NIXOS_DISK:-}" ]] && \
     command -v findmnt >/dev/null 2>&1 && command -v lsblk >/dev/null 2>&1; then
    root_source="$(findmnt -n -o SOURCE / 2>/dev/null || true)"
    if [[ "${root_source}" == /dev/* ]]; then
      detected_disk="$(
        lsblk -sno PATH,TYPE "${root_source}" 2>/dev/null |
          awk '$2 == "disk" { print $1; exit }' || true
      )"
    fi
  fi
  export DOTFILES_NIXOS_DISK="${DOTFILES_NIXOS_DISK:-${detected_disk:-/dev/vda}}"
  [[ "${DOTFILES_NIXOS_DISK}" == /dev/* ]] || \
    fail "DOTFILES_NIXOS_DISK must be an absolute /dev path."

  info "Using NixOS account ${DOTFILES_NIXOS_USER} at ${DOTFILES_NIXOS_HOME}"
  info "Using NixOS host ${DOTFILES_NIXOS_HOSTNAME} and root disk ${DOTFILES_NIXOS_DISK}"
}

configure_darwin_identity() {
  local current_uid current_user

  current_uid="$(id -u)"
  current_user="$(id -un)"

  [[ "${current_uid}" -ne 0 ]] || \
    fail "Run setup as your normal macOS user, not with sudo. It will request administrator access when needed."
  [[ -n "${current_user}" ]] || fail "Could not determine the current macOS username."
  [[ -n "${HOME:-}" && "${HOME}" == /* && -d "${HOME}" ]] || \
    fail "HOME must be an existing absolute directory for the current macOS user."

  export DOTFILES_DARWIN_USER="${current_user}"
  export DOTFILES_DARWIN_HOME="${HOME}"
  info "Using macOS account ${DOTFILES_DARWIN_USER} at ${DOTFILES_DARWIN_HOME}"
}

run_configuration_nix() {
  local platform="$1" command="$2"
  shift 2

  if [[ "${platform}" == "generic-linux" || "${platform}" == "nixos" || "${platform}" == "darwin" ]]; then
    # User identities are deliberately supplied at runtime so the same checkout
    # can activate any normal macOS, NixOS, or Ubuntu account.
    run_nix "${command}" --impure "$@"
  else
    run_nix "${command}" "$@"
  fi
}

build_ubuntu_manifest() {
  local detected_system="$1" flake="$2" manifest="$3"

  run_nix build --no-write-lock-file --no-link --print-out-paths \
    "${flake}#packages.${detected_system}.${manifest}"
}

sync_apt_packages() {
  local detected_system="$1" flake="$2" apt_get manifest package
  local -a packages=()

  apt_get="$(command -v apt-get || true)"
  [[ -n "${apt_get}" ]] || \
    fail "The declared APT packages can only be installed on Ubuntu/Debian hosts with apt-get."

  manifest="$(build_ubuntu_manifest \
    "${detected_system}" "${flake}" ubuntu-apt-packages)" || return $?

  while IFS= read -r package; do
    [[ -n "${package}" ]] || continue
    [[ "${package}" != -* && "${package}" != *[[:space:]]* ]] || \
      fail "Invalid APT package name in ${manifest}: ${package}"
    packages+=("${package}")
  done < "${manifest}"

  if (( ${#packages[@]} == 0 )); then
    info "No Ubuntu APT packages are declared"
    return 0
  fi

  info "Updating Ubuntu APT package metadata"
  sudo "${apt_get}" -o DPkg::Lock::Timeout=120 update || return $?

  info "Installing and upgrading ${#packages[@]} declared Ubuntu APT packages"
  sudo /usr/bin/env DEBIAN_FRONTEND=noninteractive \
    "${apt_get}" -o DPkg::Lock::Timeout=120 install --yes \
    "${packages[@]}" || return $?
}

sync_snap_packages() {
  local detected_system="$1" flake="$2" manifest snap_bin
  local name channel confinement
  local -a snap_args=()

  manifest="$(build_ubuntu_manifest \
    "${detected_system}" "${flake}" ubuntu-snap-packages)" || return $?
  if [[ ! -s "${manifest}" ]]; then
    info "No Ubuntu Snap packages are declared"
    return 0
  fi

  snap_bin="$(command -v snap || true)"
  [[ -n "${snap_bin}" ]] || \
    fail "snap is unavailable after APT reconciliation. Check the snapd installation and retry."

  if command -v systemctl >/dev/null 2>&1 && \
     systemctl list-unit-files snapd.socket >/dev/null 2>&1; then
    info "Ensuring the Ubuntu Snap service is available"
    sudo systemctl enable --now snapd.socket || return $?
  fi

  info "Waiting for Ubuntu Snap initialization"
  sudo "${snap_bin}" wait system seed.loaded || return $?

  while IFS=$'\t' read -r name channel confinement; do
    [[ -n "${name}" ]] || continue
    [[ "${name}" != -* && "${name}" != *[[:space:]]* ]] || \
      fail "Invalid Snap package name in ${manifest}: ${name}"
    [[ -n "${channel}" && "${channel}" != -* && "${channel}" != *[[:space:]]* ]] || \
      fail "Invalid Snap channel for ${name}: ${channel}"
    case "${confinement}" in
      strict|classic) ;;
      *) fail "Invalid Snap confinement for ${name}: ${confinement}" ;;
    esac

    if "${snap_bin}" list "${name}" >/dev/null 2>&1; then
      info "Refreshing Snap ${name} from ${channel}"
      sudo "${snap_bin}" refresh "${name}" --channel="${channel}" || return $?
    else
      snap_args=(install "${name}" --channel="${channel}")
      [[ "${confinement}" == "classic" ]] && snap_args+=(--classic)
      info "Installing Snap ${name} from ${channel} (${confinement})"
      sudo "${snap_bin}" "${snap_args[@]}" || return $?
    fi
  done < "${manifest}"
}

clean_ubuntu_package_caches() {
  local apt_get

  apt_get="$(command -v apt-get || true)"
  if [[ -z "${apt_get}" ]]; then
    info "APT is not installed; no Ubuntu package cache needs cleaning"
    return 0
  fi

  info "Cleaning downloaded Ubuntu APT packages"
  sudo "${apt_get}" clean
}

LINUXBREW_BIN=""

find_linuxbrew() {
  local candidate

  if command -v brew >/dev/null 2>&1; then
    command -v brew
    return 0
  fi

  for candidate in \
    /home/linuxbrew/.linuxbrew/bin/brew \
    "${HOME}/.linuxbrew/bin/brew"
  do
    if [[ -x "${candidate}" ]]; then
      printf '%s\n' "${candidate}"
      return 0
    fi
  done

  return 1
}

run_linuxbrew() {
  # Homebrew's repositories are public HTTPS remotes. Do not let the user's
  # GitHub HTTPS-to-SSH rewrite or SSH overrides turn brew operations into an
  # authenticated SSH request that depends on a YubiKey or local SSH key.
  env -u GIT_SSH -u GIT_SSH_COMMAND \
    GIT_CONFIG_GLOBAL=/dev/null \
    GIT_CONFIG_NOSYSTEM=1 \
    "${LINUXBREW_BIN}" "$@"
}

ensure_linuxbrew() {
  local installer prerequisite status
  local -a missing_prerequisites=()

  if LINUXBREW_BIN="$(find_linuxbrew)"; then
    return 0
  fi

  command -v apt-get >/dev/null 2>&1 || \
    fail "Automatic Linuxbrew installation currently supports Ubuntu/Debian hosts with apt-get."

  for prerequisite in build-essential procps curl file git; do
    if ! dpkg-query -W -f='${Status}\n' "${prerequisite}" 2>/dev/null | \
         grep -qx 'install ok installed'; then
      missing_prerequisites+=("${prerequisite}")
    fi
  done
  (( ${#missing_prerequisites[@]} == 0 )) || \
    fail "Linuxbrew prerequisites are missing (${missing_prerequisites[*]}). Run ${SETUP_PATH} apt first."

  installer="$(mktemp "${TMPDIR:-/tmp}/homebrew-install.XXXXXX")"
  info "Downloading the official Homebrew installer"
  if curl --fail --silent --show-error --location \
    "${HOMEBREW_INSTALL_URL}" --output "${installer}"; then
    :
  else
    status=$?
    rm -f -- "${installer}"
    return "${status}"
  fi

  info "Installing Linuxbrew in its supported prefix"
  if env -u GIT_SSH -u GIT_SSH_COMMAND \
    GIT_CONFIG_GLOBAL=/dev/null \
    GIT_CONFIG_NOSYSTEM=1 \
    PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin \
    NONINTERACTIVE=1 CI=1 /bin/bash "${installer}"; then
    :
  else
    status=$?
    rm -f -- "${installer}"
    return "${status}"
  fi
  rm -f -- "${installer}"

  LINUXBREW_BIN="$(find_linuxbrew)" || \
    fail "Homebrew finished installing, but its brew executable could not be found."
}

sync_linuxbrew() {
  local base_brewfile brewfile cask_candidates cask_json supported_casks
  local detected_system="$1" flake="$2" linux_platform status supported_count
  local -a casks=()

  ensure_linuxbrew || return $?
  base_brewfile="$(run_nix build --no-write-lock-file --no-link --print-out-paths \
    "${flake}#packages.${detected_system}.linuxbrew-brewfile")" || return $?
  cask_candidates="$(run_nix build --no-write-lock-file --no-link --print-out-paths \
    "${flake}#packages.${detected_system}.linuxbrew-cask-candidates")" || return $?

  brewfile="$(mktemp "${TMPDIR:-/tmp}/dotfiles-Brewfile.XXXXXX")"
  if cp -- "${base_brewfile}" "${brewfile}"; then
    :
  else
    status=$?
    rm -f -- "${brewfile}"
    return "${status}"
  fi

  case "$(uname -m)" in
    x86_64) linux_platform="x86_64_linux" ;;
    aarch64|arm64) linux_platform="arm64_linux" ;;
    *) fail "Unsupported Linuxbrew architecture: $(uname -m)" ;;
  esac

  info "Updating Linuxbrew"
  if run_linuxbrew update; then
    :
  else
    status=$?
    rm -f -- "${brewfile}"
    return "${status}"
  fi

  mapfile -t casks < "${cask_candidates}"
  if (( ${#casks[@]} > 0 )); then
    cask_json="$(mktemp "${TMPDIR:-/tmp}/dotfiles-casks.XXXXXX.json")"
    supported_casks="$(mktemp "${TMPDIR:-/tmp}/dotfiles-supported-casks.XXXXXX")"

    # The Ruby program intentionally uses Ruby's $stdin global.
    # shellcheck disable=SC2016
    if run_linuxbrew info --json=v2 --cask "${casks[@]}" > "${cask_json}" && \
      run_linuxbrew ruby -rjson -e '
        JSON.parse($stdin.read).fetch("casks", []).each do |cask|
          platforms = cask.fetch("supported_platforms", [])
          puts cask.fetch("token") if platforms.include?(ARGV.fetch(0))
        end
      ' "${linux_platform}" < "${cask_json}" > "${supported_casks}"; then
      while IFS= read -r cask; do
        [[ -n "${cask}" ]] && printf 'cask "%s"\n' "${cask}" >> "${brewfile}"
      done < "${supported_casks}"
      supported_count="$(wc -l < "${supported_casks}")"
      supported_count="${supported_count//[[:space:]]/}"
      info "Including ${supported_count} macOS cask candidates with native Linux support"
    else
      warn "Could not determine Linux-compatible casks; continuing with portable formulae only."
    fi

    rm -f -- "${cask_json}" "${supported_casks}"
  fi

  info "Installing and upgrading the Linux-compatible macOS Homebrew bundle"
  if run_linuxbrew bundle install --upgrade --force-cleanup \
    --file="${brewfile}"; then
    :
  else
    status=$?
    rm -f -- "${brewfile}"
    return "${status}"
  fi
  rm -f -- "${brewfile}"

  info "Cleaning old Linuxbrew versions and downloads"
  run_linuxbrew cleanup || return $?
}

clean_linuxbrew() {
  if ! LINUXBREW_BIN="$(find_linuxbrew)"; then
    info "Linuxbrew is not installed; no Homebrew files need cleaning"
    return 0
  fi

  info "Cleaning Linuxbrew downloads and old formula versions"
  run_linuxbrew cleanup --prune=7
}

DARWIN_BUILD_OUTPUT=""

run_darwin_nix_build() {
  local build_log failed_user status
  build_log="$(mktemp "${TMPDIR:-/tmp}/dotfiles-nix-build.XXXXXX")"
  DARWIN_BUILD_OUTPUT=""

  if DARWIN_BUILD_OUTPUT="$(run_nix build "$@" 2> >(/usr/bin/tee "${build_log}" >&2))"; then
    rm -f -- "${build_log}"
    return 0
  else
    status=$?
  fi

  failed_user="$({
    awk -F "'" '/the user .* in the group .* does not exist/ { print $2; exit }' "${build_log}"
  } || true)"

  if [[ -z "${failed_user}" ]]; then
    rm -f -- "${build_log}"
    return "${status}"
  fi

  if ! id "${failed_user}" >/dev/null 2>&1; then
    warn "The Nix build account ${failed_user} is missing from macOS Directory Services. Follow https://github.com/NixOS/nix/issues/10892 to repair the macOS build users before retrying."
    rm -f -- "${build_log}"
    return "${status}"
  fi

  warn "The Nix daemon has stale information for ${failed_user}; restarting it and retrying the build once."
  if ! sudo /bin/launchctl kickstart -k system/org.nixos.nix-daemon; then
    warn "Could not restart the Nix daemon."
    rm -f -- "${build_log}"
    return "${status}"
  fi

  if DARWIN_BUILD_OUTPUT="$(run_nix build "$@")"; then
    rm -f -- "${build_log}"
    return 0
  else
    status=$?
    rm -f -- "${build_log}"
    return "${status}"
  fi
}

repair_darwin_application_store_paths() {
  local system_path="$1" applications_path link relative store_path target
  local repaired=0

  while IFS= read -r applications_path; do
    case "${applications_path}" in
      /nix/store/*-system-applications) ;;
      *) continue ;;
    esac

    [[ -d "${applications_path}/Applications" ]] || continue

    while IFS= read -r link; do
      [[ -e "${link}" ]] && continue
      target="$(readlink "${link}")"

      case "${target}" in
        /nix/store/*/*)
          relative="${target#/nix/store/}"
          store_path="/nix/store/${relative%%/*}"
          ;;
        *)
          fail "Managed application ${link} has an unexpected missing target: ${target}"
          ;;
      esac

      warn "Repairing deleted Nix-managed application store path ${store_path}"
      run_nix build --no-link --repair "${store_path}" || \
        fail "Could not restore ${store_path}. Check the configured Nix substituters and retry."
      [[ -e "${link}" ]] || \
        fail "Nix reported a successful repair, but ${link} is still missing its target."
      repaired=1
    done < <(find "${applications_path}/Applications" -type l -print)
  done < <(nix-store --query --requisites "${system_path}")

  if (( repaired )); then
    info "Deleted Nix-managed applications were restored before activation"
  fi
}

update_secrets_lock() {
  local identity="${SECRETS_UPDATE_IDENTITY:-}"
  local remote_revision ssh_command=""

  command -v git >/dev/null 2>&1 || fail "Git is required to update the secrets lock entry."

  if [[ -n "${identity}" ]]; then
    [[ -r "${identity}" ]] || fail "Secrets update identity is not readable: ${identity}"
    printf -v ssh_command 'ssh -i %q -o IdentitiesOnly=yes' "${identity}"
    info "Using ${identity} to authenticate the secrets lock refresh"
  fi

  remote_revision="$(
    if [[ -n "${ssh_command}" ]]; then
      GIT_SSH_COMMAND="${ssh_command}" \
        git ls-remote "${SECRETS_REMOTE}" refs/heads/main
    else
      git ls-remote "${SECRETS_REMOTE}" refs/heads/main
    fi |
      awk '$2 == "refs/heads/main" { print $1; exit }' || true
  )"

  [[ -n "${remote_revision}" ]] || \
    fail "Could not read the secrets repository's main branch. Retry from an interactive terminal after making the GPG-backed identity registered with GitHub available to SSH."

  if grep -Fq -- "\"rev\": \"${remote_revision}\"" "${FLAKE_DIR}/flake.lock"; then
    info "Secrets lock entry is already current at ${remote_revision}"
    if [[ -n "${identity}" ]]; then
      warn "The recovery identity can read the repository, but the GPG-backed SSH identity could not. Register the authentication key reported by ./setup gpg with GitHub before running switch."
    fi
    return 0
  fi

  if [[ -n "${ssh_command}" ]]; then
    GIT_SSH_COMMAND="${ssh_command}" \
      run_nix flake update secrets --flake "${FLAKE_DIR}" || return $?
  else
    run_nix flake update secrets --flake "${FLAKE_DIR}" || return $?
  fi
  grep -Fq -- "\"rev\": \"${remote_revision}\"" "${FLAKE_DIR}/flake.lock" || \
    fail "Nix did not lock secrets to the current main revision ${remote_revision}."

  info "Secrets lock entry updated to ${remote_revision}; run switch to activate the configuration"
}

run_action() {
  local action="$1"
  shift

  case "${action}" in
    switch|build|check|apply|apt|snaps|github-user|set-github-user|github-ssh-key|doctor|clean|install-nix|update-secrets|pull-secrets|refresh-secrets-lock|gpg|cache-gpg-pin|check-keys|copy-keys|create-keys|yubikey-login|yubikey-agenix|yubikey-setup) ;;
    -h|--help) usage; return 0 ;;
    *) usage >&2; fail "Unknown action: ${action}" ;;
  esac

  if [[ "${action}" == "github-user" || "${action}" == "set-github-user" ]]; then
    change_github_username "$@"
    return $?
  fi

  if [[ "${action}" == "github-ssh-key" ]]; then
    configure_github_username
    register_github_ssh_key
    return $?
  fi

  if [[ "${action}" == "doctor" ]]; then
    "${REPO_ROOT}/doctor" "$@"
    return $?
  fi

  if [[ "${action}" == "yubikey-login" ]]; then
    info "Configuring local computer login with a YubiKey PIN"
    "${REPO_ROOT}/yubikey-login" "$@" || return $?
    if [[ -e /etc/NIXOS && "${1:-}" != "--status" && "${1:-}" != "--disable" ]]; then
      info "Activating the declarative NixOS login configuration"
      run_action switch
    fi
    return $?
  fi

  if [[ "${action}" == "yubikey-agenix" ]]; then
    case "${1:---enroll}" in
      --enroll|--enroll-only|--repair-management-key|--test)
        if [[ -e /etc/NIXOS ]] && \
           ! systemctl is-active --quiet pcscd.socket 2>/dev/null && \
           ! systemctl is-active --quiet pcscd.service 2>/dev/null; then
          info "Activating the NixOS smart-card service before provisioning"
          run_action switch || return $?
        fi
        ;;
    esac
    # Select the same managed GnuPG suite used by the other key actions. This
    # ensures yubikey-agenix terminates the scdaemon that actually owns the
    # reader instead of an older distribution instance on Ubuntu.
    prepare_gpg_ssh_agent
    info "Configuring hardware-backed Agenix encryption"
    "${REPO_ROOT}/yubikey-agenix" "$@"
    return $?
  fi

  if [[ "${action}" == "yubikey-setup" ]]; then
    local provision_yubikey=yes enrol_yubikey_login=yes yubikey_option
    for yubikey_option in "$@"; do
      case "${yubikey_option}" in
        --help|-h|--status) provision_yubikey=no ;;
        --skip-login) enrol_yubikey_login=no ;;
      esac
    done
    if [[ "${provision_yubikey}" == yes && -e /etc/NIXOS ]] && \
       ! systemctl is-active --quiet pcscd.socket 2>/dev/null && \
       ! systemctl is-active --quiet pcscd.service 2>/dev/null; then
      info "Activating the NixOS smart-card service before provisioning"
      run_action switch || return $?
    fi
    # This action returns before the general build/switch preparation below,
    # so reconcile the GnuPG client, agent, and scdaemon explicitly. Without
    # this, Ubuntu can run the managed client against an older socket-activated
    # distribution agent and fail to discover an otherwise visible YubiKey.
    prepare_gpg_ssh_agent
    info "Provisioning one connected YubiKey"
    "${REPO_ROOT}/yubikey-setup" "$@" || return $?
    if [[ "${provision_yubikey}" == yes && "${enrol_yubikey_login}" == yes && -e /etc/NIXOS ]]; then
      info "Activating the declarative NixOS login configuration"
      run_action switch
    fi
    return $?
  fi

  configure_github_username

  if [[ "${action}" == "install-nix" ]]; then
    install_or_reinstall_nix
    return $?
  fi

  [[ -f "${FLAKE_DIR}/flake.nix" ]] || fail "Expected flake at ${FLAKE_DIR}/flake.nix."

  if [[ "${action}" == "update-secrets" || "${action}" == "pull-secrets" || "${action}" == "refresh-secrets-lock" ]]; then
    load_nix || install_nix
    prepare_gpg_ssh_agent

    if [[ "${action}" == "update-secrets" ]]; then
      info "Encrypting and pushing local secrets"
      SECRETS_CONFIG_EXTERNAL_FALLBACK="${FLAKE_DIR}/modules/shared/config/ssh/config_external" \
        "${FLAKE_DIR}/apps/shared/secrets-sync" push || return $?
    elif [[ "${action}" == "pull-secrets" ]]; then
      info "Pulling and decrypting private secrets"
      "${FLAKE_DIR}/apps/shared/secrets-sync" pull || return $?
    fi

    info "Refreshing only the private secrets lock entry"
    if [[ -n "${SECRETS_UPDATE_IDENTITY:-}" || -n "${SECRETS_SSH_IDENTITY:-}" ]]; then
      SECRETS_UPDATE_IDENTITY="${SECRETS_UPDATE_IDENTITY:-${SECRETS_SSH_IDENTITY:-}}" \
        update_secrets_lock
    else
      update_secrets_lock
    fi
    return $?
  fi

  if [[ "${action}" == "gpg" || "${action}" == "cache-gpg-pin" || "${action}" == "check-keys" || "${action}" == "copy-keys" || "${action}" == "create-keys" ]]; then
    prepare_gpg_ssh_agent
    info "Running ${action}"
    "${FLAKE_DIR}/apps/shared/${action}" "$@" || return $?
    info "${action} completed"
    return 0
  fi

  local detected_system config flake output platform
  detected_system="$(system_name)"
  flake="path:${FLAKE_DIR}"
  platform="$(platform_kind)"

  case "${platform}" in
    darwin) configure_darwin_identity ;;
    nixos) configure_nixos_identity ;;
    generic-linux) configure_generic_linux_identity ;;
  esac

  if ! load_nix; then
    if [[ "${platform}" == "nixos" ]]; then
      fail "Nix is unavailable on NixOS; repair the system installation before continuing."
    fi
    install_nix
  fi

  if [[ -n "${SYSTEM_CONFIG:-}" ]]; then
    config="${SYSTEM_CONFIG}"
  elif [[ "${platform}" == "darwin" ]]; then
    config="$(darwin_configuration_name "${detected_system}")"
  else
    config="${detected_system}"
  fi

  prepare_gpg_ssh_agent

  info "Using ${config} from ${FLAKE_DIR}"

  case "${action}" in
    apt)
      [[ "${platform}" == "generic-linux" ]] || \
        fail "The apt action is only available on Ubuntu/Debian hosts using the standalone Home Manager configuration."
      info "Reconciling declared Ubuntu APT packages"
      sync_apt_packages "${detected_system}" "${flake}" || return $?
      info "APT package reconciliation completed"
      return 0
      ;;
    snaps)
      [[ "${platform}" == "generic-linux" ]] || \
        fail "The snaps action is only available on Ubuntu/Debian hosts using the standalone Home Manager configuration."
      info "Ensuring Snap's declared Ubuntu host dependencies are installed"
      sync_apt_packages "${detected_system}" "${flake}" || return $?
      info "Reconciling declared Ubuntu Snap packages"
      sync_snap_packages "${detected_system}" "${flake}" || return $?
      info "Snap package reconciliation completed"
      return 0
      ;;
    apply)
      if [[ "${platform}" == "generic-linux" ]]; then
        info "Applying the standalone Home Manager configuration"
        run_action switch "$@"
        return $?
      fi
      info "Running ${action}"
      (
        cd "${FLAKE_DIR}"
        run_configuration_nix "${platform}" run --no-write-lock-file \
          "${flake}#${action}" -- "$@"
      ) || return $?
      info "${action} completed"
      return 0
      ;;
    clean)
      info "Running ${action}"
      (
        cd "${FLAKE_DIR}"
        run_configuration_nix "${platform}" run --no-write-lock-file \
          "${flake}#${action}" -- "$@"
      ) || return $?
      if [[ "${platform}" == "generic-linux" ]]; then
        clean_linuxbrew || return $?
        clean_ubuntu_package_caches || return $?
      fi
      info "${action} completed"
      return 0
      ;;
  esac

  case "${platform}" in
    darwin)
      output="darwinConfigurations.${config}.system"
      ;;
    nixos)
      output="nixosConfigurations.${config}.config.system.build.toplevel"
      ;;
    generic-linux)
      output="homeConfigurations.${config}.activationPackage"
      ;;
  esac

  case "${action}" in
    check)
      run_configuration_nix "${platform}" eval --no-write-lock-file --raw \
        "${flake}#${output}.drvPath" || return $?
      printf '\n'
      ;;
    build)
      if [[ "${platform}" == "darwin" ]]; then
        run_darwin_nix_build --impure --no-write-lock-file --print-build-logs \
          --no-link --print-out-paths "${flake}#${output}" || return $?
        repair_darwin_application_store_paths "${DARWIN_BUILD_OUTPUT}"
      else
        run_configuration_nix "${platform}" build --no-write-lock-file \
          --print-build-logs --no-link "${flake}#${output}" || return $?
      fi
      ;;
    switch)
      if [[ "${platform}" == "darwin" ]]; then
        local result

        info "Building before activation"
        run_darwin_nix_build --impure --no-write-lock-file --print-build-logs \
          --no-link --print-out-paths "${flake}#${output}" || return $?
        result="${DARWIN_BUILD_OUTPUT}"
        repair_darwin_application_store_paths "${result}"

        info "Activating the macOS configuration"
        sudo /usr/bin/env \
          DOTFILES_DARWIN_USER="${DOTFILES_DARWIN_USER}" \
          DOTFILES_DARWIN_HOME="${DOTFILES_DARWIN_HOME}" \
          DOTFILES_GITHUB_USER="${DOTFILES_GITHUB_USER}" \
          SSH_AUTH_SOCK="${SSH_AUTH_SOCK:-}" \
          "${result}/sw/bin/darwin-rebuild" switch --impure \
          --flake "${flake}#${config}" || return $?
      elif [[ "${platform}" == "nixos" ]]; then
        info "Building and activating the NixOS configuration"
        sudo \
          DOTFILES_NIXOS_USER="${DOTFILES_NIXOS_USER}" \
          DOTFILES_NIXOS_HOME="${DOTFILES_NIXOS_HOME}" \
          DOTFILES_NIXOS_HOSTNAME="${DOTFILES_NIXOS_HOSTNAME}" \
          DOTFILES_NIXOS_DISK="${DOTFILES_NIXOS_DISK}" \
          DOTFILES_GITHUB_USER="${DOTFILES_GITHUB_USER}" \
          SSH_AUTH_SOCK="${SSH_AUTH_SOCK:-}" \
          /run/current-system/sw/bin/nixos-rebuild switch --impure \
          --flake "${flake}#${config}" || return $?
      else
        local result backup_extension

        info "Building the standalone Home Manager configuration"
        result="$(run_configuration_nix "${platform}" build \
          --no-write-lock-file --print-build-logs \
          --no-link --print-out-paths "${flake}#${output}")" || return $?

        info "Activating the Ubuntu Home Manager configuration"
        backup_extension="bk-$(date +%Y%m%d%H%M%S)-$$"
        USER="${DOTFILES_LINUX_USER}" LOGNAME="${DOTFILES_LINUX_USER}" \
          HOME="${DOTFILES_LINUX_HOME}" \
          HOME_MANAGER_BACKUP_EXT="${backup_extension}" \
          "${result}/activate" || return $?

        sync_apt_packages "${detected_system}" "${flake}" || return $?
        sync_snap_packages "${detected_system}" "${flake}" || return $?
        sync_linuxbrew "${detected_system}" "${flake}" || return $?
      fi
      ;;
  esac

  info "Configuration ${action} completed"
}

print_menu() {
  cat <<'EOF'

Choose an action:
   1) switch       Build and activate the configuration
   2) build        Build without activating
   3) check        Evaluate without building
   4) apply        Personalize the configuration
   5) clean        Remove old system generations
   6) gpg          Start and verify GPG-backed SSH
   7) cache-gpg-pin
                    Cache one YubiKey's signature PIN until it is removed
   8) check-keys   Verify keys and the GPG agent
   9) copy-keys    Copy keys from a mounted drive
  10) create-keys  Create SSH and Agenix keys
  11) install-nix  Install or replace with upstream Nix
  12) update-secrets
                    Encrypt secrets plus a durable ~/.ssh archive
  13) pull-secrets  Back up and restore encrypted SSH secrets
  14) refresh-secrets-lock
                    Refresh only the private secrets lock entry
  15) github-user  Show or change the saved GitHub username
  16) yubikey-login
                    Enable local computer login with a YubiKey PIN
  17) yubikey-agenix
                    Provision a YubiKey for Agenix encryption
  18) yubikey-setup
                    Provision PINs, keys, login, SSH, and Agenix for one card
  19) apt          Install and upgrade declared Ubuntu APT packages
  20) snaps        Install and refresh declared Ubuntu Snap packages
  21) github-ssh-key
                    Register this YubiKey's OpenPGP SSH key with GitHub
  22) doctor        Validate scripts, Nix, Emacs, GnuPG, and GitHub SSH
   q) quit
EOF
}

interactive_menu() {
  local choice action action_status

  while true; do
    print_menu
    if ! IFS= read -r -p "Which action would you like to take? " choice; then
      printf '\n'
      info "Exiting setup"
      return 0
    fi

    case "${choice}" in
      1|switch) action="switch" ;;
      2|build) action="build" ;;
      3|check) action="check" ;;
      4|apply) action="apply" ;;
      5|clean) action="clean" ;;
      6|gpg) action="gpg" ;;
      7|cache-gpg-pin) action="cache-gpg-pin" ;;
      8|check-keys) action="check-keys" ;;
      9|copy-keys) action="copy-keys" ;;
      10|create-keys) action="create-keys" ;;
      11|i|install-nix) action="install-nix" ;;
      12|update-secrets) action="update-secrets" ;;
      13|pull-secrets) action="pull-secrets" ;;
      14|refresh-secrets-lock) action="refresh-secrets-lock" ;;
      15|github-user|set-github-user) action="github-user" ;;
      16|yubikey-login) action="yubikey-login" ;;
      17|yubikey-agenix) action="yubikey-agenix" ;;
      18|yubikey-setup) action="yubikey-setup" ;;
      19|apt) action="apt" ;;
      20|snaps|snap) action="snaps" ;;
      21|github-ssh-key) action="github-ssh-key" ;;
      22|doctor) action="doctor" ;;
      q|Q|quit|exit)
        info "Exiting setup"
        return 0
        ;;
      "") continue ;;
      *)
        printf '\033[1;31mInvalid selection:\033[0m %s\n' "${choice}" >&2
        continue
        ;;
    esac

    printf '\n'
    if (run_action "${action}"); then
      :
    else
      action_status=$?
      printf '\033[1;31mAction %s failed with status %s.\033[0m\n' \
        "${action}" "${action_status}" >&2
    fi
  done
}

main() {
  if [[ $# -eq 0 ]]; then
    configure_github_username
    interactive_menu
  else
    run_action "$@"
  fi
}

if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
  main "$@"
fi