delivery: scope safe QuickShell surface adoption

scripts/install-quickshell-surface.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# Safely adopt the Souveraine QuickShell surface into an existing ii setup.
+#
+# This is deliberately separate from pacman installation: packages place
+# assets on disk, while a person chooses whether their live shell may change.
+set -euo pipefail
+
+usage() {
+    cat <<'EOF'
+Usage: install-quickshell-surface.sh [--dry-run | --apply | --adopt]
+
+  --dry-run  Show every file the Souveraine surface would manage (default).
+  --apply    Install when every target is new or already Souveraine-managed.
+  --adopt    Permit replacing existing ii files after preserving a timestamped
+             copy beside each conflict. Implies --apply.
+
+Pacman should install surface assets only. This command is the explicit,
+user-owned step that changes ~/.config/quickshell/ii.
+EOF
+}
+
+mode=dry-run
+adopt=false
+while (($#)); do
+    case "$1" in
+        --dry-run) mode=dry-run ;;
+        --apply) mode=apply ;;
+        --adopt) mode=apply; adopt=true ;;
+        -h|--help) usage; exit 0 ;;
+        *) echo "unknown option: $1" >&2; usage >&2; exit 2 ;;
+    esac
+    shift
+done
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+DEPLOY="$ROOT/surfaces/quickshell/deploy.sh"
+QS="${XDG_CONFIG_HOME:-$HOME/.config}/quickshell"
+II="$QS/ii"
+
+[[ -x "$DEPLOY" ]] || { echo "surface deployer not found: $DEPLOY" >&2; exit 1; }
+[[ -d "$II" ]] || {
+    echo "No ii QuickShell configuration at $II." >&2
+    echo "Install and initialise QuickShell/illogical-impulse first; no files changed." >&2
+    exit 1
+}
+
+conflicts=()
+new_count=0
+managed_count=0
+
+while read -r rel target; do
+    src="$ROOT/surfaces/quickshell/$rel"
+    dst="$QS/$target"
+    [[ -f "$src" ]] || { echo "surface source missing: $src" >&2; exit 1; }
+
+    if [[ -L "$dst" && "$(readlink -f "$dst")" == "$src" ]]; then
+        printf 'managed  %s\n' "$target"
+        ((managed_count += 1))
+    elif [[ -e "$dst" || -L "$dst" ]]; then
+        printf 'replace  %s\n' "$target"
+        conflicts+=("$target")
+    else
+        printf 'new      %s\n' "$target"
+        ((new_count += 1))
+    fi
+done < <("$DEPLOY" --manifest)
+
+printf '\n%d managed, %d new, %d replacement(s).\n' \
+    "$managed_count" "$new_count" "${#conflicts[@]}"
+
+if [[ "$mode" == dry-run ]]; then
+    echo "Dry run only; use --apply when there are no replacements, or --adopt to preserve and replace them."
+    exit 0
+fi
+
+if ((${#conflicts[@]}) > 0) && [[ "$adopt" != true ]]; then
+    echo "Refusing to replace existing ii files without --adopt. No files changed." >&2
+    exit 2
+fi
+
+if ((${#conflicts[@]}) > 0); then
+    stamp="$(date +%Y%m%d-%H%M%S)"
+    for target in "${conflicts[@]}"; do
+        dst="$QS/$target"
+        backup="${dst}.pre-souveraine-${stamp}"
+        cp -a -- "$dst" "$backup"
+        echo "preserved $target -> ${backup#$QS/}"
+    done
+fi
+
+exec "$DEPLOY"