refactor: decompose install_btrfs into named orchestration stages

Pull the single-vs-multi-disk and LUKS-vs-no-encryption branching out
of install_btrfs() into five helpers in lib/btrfs.sh:

- btrfs_open_encryption         — LUKS open + fill devices array
- btrfs_make_filesystem         — create_btrfs_volume dispatch
- btrfs_configure_luks_target   — in-chroot LUKS config
- btrfs_install_grub            — GRUB primary + multi-disk mirror
- btrfs_close_encryption        — LUKS close (cleanup)

Helpers use namerefs (local -n) to take the caller's arrays as locals
instead of promoting them to globals. install_btrfs() drops from ~99
lines of nested if-then-else to a ~45-line flat sequence of named
stages — matching the style of install_zfs().

Behavior preserved — this is pure code movement, no new disk/LUKS
operations. No unit tests added for the new helpers: they all wrap
real LUKS/mkfs.btrfs calls that need block devices and root; VM
integration tests in scripts/test-install.sh remain the source of
truth. .shellcheckrc: disable SC2178 (nameref array heuristic) and
SC2153 (globals from sourced files) — both recurring false positives.

make test: 65/65. shellcheck clean.

1 files changed, 80 insertions, 0 deletions

diff --git a/installer/lib/btrfs.sh b/installer/lib/btrfs.sh
index 4e11e2f..f1cfaac 100644
--- a/installer/lib/btrfs.sh
+++ b/installer/lib/btrfs.sh
@@ -901,3 +901,83 @@ btrfs_cleanup() {
 
     info "Btrfs cleanup complete."
 }
+
+#############################
+# Btrfs Install Orchestration
+#############################
+# These helpers dispatch single-disk vs multi-disk branches that used
+# to live inline in install_btrfs(). They use namerefs so the caller's
+# arrays stay as locals in install_btrfs.
+
+# Open LUKS containers (if encryption enabled) and fill _devices with
+# either /dev/mapper/* names or the raw partitions.
+# Usage: btrfs_open_encryption ROOT_PARTS_VAR OUT_DEVICES_VAR
+btrfs_open_encryption() {
+    local -n _root_parts="$1"
+    local -n _devices="$2"
+    local num_disks=${#SELECTED_DISKS[@]}
+
+    if [[ "$NO_ENCRYPT" == "yes" ]]; then
+        _devices=("${_root_parts[@]}")
+        return 0
+    fi
+
+    if [[ $num_disks -eq 1 ]]; then
+        create_luks_container "${_root_parts[0]}" "$LUKS_PASSPHRASE"
+        open_luks_container   "${_root_parts[0]}" "$LUKS_PASSPHRASE"
+        _devices=("/dev/mapper/$LUKS_MAPPER_NAME")
+    else
+        create_luks_containers "$LUKS_PASSPHRASE" "${_root_parts[@]}"
+        open_luks_containers   "$LUKS_PASSPHRASE" "${_root_parts[@]}"
+        # shellcheck disable=SC2207
+        _devices=($(get_luks_devices "$num_disks"))
+    fi
+}
+
+# Create the btrfs filesystem: plain for single disk, raided for multi.
+# Usage: btrfs_make_filesystem DEVICES_VAR
+btrfs_make_filesystem() {
+    local -n _devices="$1"
+    local num_disks=${#SELECTED_DISKS[@]}
+
+    if [[ $num_disks -eq 1 ]]; then
+        create_btrfs_volume "${_devices[0]}"
+    else
+        create_btrfs_volume "${_devices[@]}" --raid-level "$RAID_LEVEL"
+    fi
+}
+
+# Run the in-chroot LUKS configuration (no-op if encryption disabled).
+# Usage: btrfs_configure_luks_target ROOT_PARTS_VAR
+btrfs_configure_luks_target() {
+    local -n _root_parts="$1"
+    [[ "$NO_ENCRYPT" == "yes" ]] && return 0
+    setup_luks_testing_keyfile "$LUKS_PASSPHRASE" "${_root_parts[@]}"
+    configure_crypttab         "${_root_parts[@]}"
+    configure_luks_grub        "${_root_parts[0]}"
+    configure_luks_initramfs
+}
+
+# Install GRUB to the first EFI partition, then mirror to any others.
+# Usage: btrfs_install_grub EFI_PARTS_VAR
+btrfs_install_grub() {
+    local -n _efi_parts="$1"
+    local num_disks=${#SELECTED_DISKS[@]}
+
+    configure_grub "${_efi_parts[0]}"
+    if [[ $num_disks -gt 1 ]]; then
+        install_grub_all_efi  "${_efi_parts[@]}"
+        create_grub_sync_hook "${_efi_parts[@]}"
+    fi
+}
+
+# Close LUKS containers opened during install (no-op if encryption disabled).
+btrfs_close_encryption() {
+    [[ "$NO_ENCRYPT" == "yes" ]] && return 0
+    local num_disks=${#SELECTED_DISKS[@]}
+    if [[ $num_disks -eq 1 ]]; then
+        close_luks_container
+    else
+        close_luks_containers "$num_disks"
+    fi
+}