feat: improve bootstrap and README portability

.doom.d/config.el

@@ -138,15 +138,10 @@
  "C-+" #'text-scale-increase ;; this was reset font size lol
   )
 
- (:after evil
+ (:after evil-org
   :map evil-org-mode-map
-   :m "g j" nil
-   :m "g k" nil
-;; (evil-global-set-key 'motion "j" 'evil-next-visual-line) ;; both of these
-;; (evil-global-set-key 'motion "k" 'evil-previous-visual-line) ;; are needed for org mode where g-j doesn't work properly
-
- ;; :desc "go down visual line"  "g j" nil
- ;; :desc "go down visual line"  "g k" nil
+      :n "g j" #'evil-next-visual-line
+      :n "g k" #'evil-previous-visual-line
  )
  (:leader
       :desc "ws 0" "0" #'eyebrowse-switch-to-window-config-0

.local/scripts/bootstrap/arch

@@ -3,9 +3,11 @@
 set -euo pipefail
 
 ### VARIABLES
-scripts="$HOME/.local/scripts"
-source "$scripts/bootstrap/base_functions"
-source "$scripts/bootstrap/arch_functions"
+bootstrap_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DOTFILES_ROOT="$(cd "$bootstrap_dir/../../.." && pwd)"
+export DOTFILES_ROOT
+source "$bootstrap_dir/base_functions"
+source "$bootstrap_dir/arch_functions"
 parse_bootstrap_args "$@"
 configure_dual_boot_utc_rtc
 
@@ -16,6 +18,8 @@ resolve_first_run_choice
 info "Updating system..."
 sudo pacman -Syu
 
+bootstrap_stow_checkout arch
+
 install_preparation
 
 echo "#! /bin/sh

.local/scripts/bootstrap/arch_functions

@@ -11,7 +11,7 @@
 #npm by default is system-wide unless using npm_config_prefix then npm install packageName will install package in user
 ### VARIABLES
 
-scripts="$HOME/.local/scripts"
+scripts="${DOTFILES_ROOT:-$HOME}/.local/scripts"
 flags="-S --noconfirm --needed"
 pac="sudo pacman $flags"
 yay="yay $flags"

.local/scripts/bootstrap/base_functions

@@ -11,6 +11,7 @@ error() { printf '\033[1;31m[ERROR]\033[0m %s\n' "$*" >&2; }
 parse_bootstrap_args() {
     DUAL_BOOT_UTC=false
     UNATTENDED=false
+    SKIP_STOW=false
     FIRST_RUN_CHOICE=""
     HIGH_DPI_CHOICE=""
 
@@ -22,6 +23,9 @@ parse_bootstrap_args() {
             --unattended)
                 UNATTENDED=true
                 ;;
+            --no-stow)
+                SKIP_STOW=true
+                ;;
             --first-run=yes|--first-run=no)
                 FIRST_RUN_CHOICE="${1#*=}"
                 ;;
@@ -36,7 +40,113 @@ parse_bootstrap_args() {
         shift
     done
 
-    export DUAL_BOOT_UTC UNATTENDED FIRST_RUN_CHOICE HIGH_DPI_CHOICE
+    export DUAL_BOOT_UTC UNATTENDED SKIP_STOW FIRST_RUN_CHOICE HIGH_DPI_CHOICE
+}
+
+## Return the dotfiles checkout root used by this bootstrap invocation.
+bootstrap_repository_root() {
+    if [ -n "${DOTFILES_ROOT:-}" ] && [ -d "$DOTFILES_ROOT" ]; then
+        printf '%s\n' "$DOTFILES_ROOT"
+        return 0
+    fi
+
+    cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd
+}
+
+## Report whether this bootstrap invocation can obtain a confirmation response.
+bootstrap_stdin_is_interactive() {
+    [ -t 0 ] && [ -t 1 ]
+}
+
+## Ask whether to apply the displayed Stow and conflict-backup plan.
+bootstrap_confirm_stow() {
+    local answer
+    read -r -p "Apply the displayed Stow plan? [y/N] " answer
+    [[ "$answer" =~ ^([yY][eE][sS]|[yY])$ ]]
+}
+
+## Return whether GNU Stow is available on the current PATH.
+bootstrap_stow_is_available() {
+    command -v stow >/dev/null 2>&1
+}
+
+## Install GNU Stow through the package manager for the selected profile.
+bootstrap_install_stow() {
+    local profile="$1"
+
+    info "GNU Stow is required to link this checkout; installing it for $profile..."
+    case "$profile" in
+        ubuntu|ubuntu-windows|work)
+            sudo apt-get install -y stow
+            ;;
+        arch|manjaro)
+            sudo pacman -S --noconfirm --needed stow
+            ;;
+        mac)
+            if ! command -v brew >/dev/null 2>&1; then
+                if declare -F brew_install >/dev/null 2>&1; then
+                    brew_install
+                else
+                    error "Homebrew is required to install GNU Stow on macOS."
+                    return 1
+                fi
+            fi
+            brew install stow
+            ;;
+        *)
+            error "No GNU Stow installer is configured for bootstrap profile: $profile"
+            return 2
+            ;;
+    esac
+
+    if ! bootstrap_stow_is_available; then
+        error "GNU Stow installation did not make the stow command available."
+        return 1
+    fi
+}
+
+## Preview and, with confirmation, link the current checkout through GNU Stow.
+bootstrap_stow_checkout() {
+    local profile="$1"
+    local dotfiles_root parent_dir package_name preview
+
+    if [ "${SKIP_STOW:-false}" = true ]; then
+        info "Skipping Stow linking (--no-stow); continuing from the checkout paths."
+        return 0
+    fi
+
+    if [ "${UNATTENDED:-false}" = true ] || ! bootstrap_stdin_is_interactive; then
+        warn "Stow linking was not applied because confirmation is unavailable. Continuing from checkout paths; rerun interactively or pass --no-stow."
+        return 0
+    fi
+
+    if ! bootstrap_stow_is_available; then
+        bootstrap_install_stow "$profile"
+    fi
+
+    dotfiles_root="$(bootstrap_repository_root)"
+    parent_dir="$(dirname "$dotfiles_root")"
+    package_name="$(basename "$dotfiles_root")"
+    preview="$(stow -v -n -t "$HOME" -d "$parent_dir" "$package_name" 2>&1 || true)"
+
+    info "Stow dry run for $dotfiles_root:"
+    if [ -n "$preview" ]; then
+        printf '%s\n' "$preview"
+    else
+        info "No Stow changes are needed."
+        return 0
+    fi
+
+    info "Conflict backup plan:"
+    bash "$dotfiles_root/.local/scripts/stow-backup-conflicts" --dry-run
+
+    if ! bootstrap_confirm_stow; then
+        info "Stow linking declined; continuing from checkout paths."
+        return 0
+    fi
+
+    bash "$dotfiles_root/.local/scripts/stow-backup-conflicts"
+    stow -v -t "$HOME" -d "$parent_dir" "$package_name"
 }
 
 resolve_first_run_choice() {
@@ -148,6 +258,7 @@ configure_dual_boot_utc_rtc() {
 install_preparation() {
     info "Preparing environment..."
 
+    mkdir -p "$HOME/.vim"
     echo "colorscheme onedark
     set background=dark" > "$HOME/.vim/theme"
 

.local/scripts/bootstrap/mac

@@ -3,16 +3,19 @@
 set -euo pipefail
 
 ### VARIABLES
-scripts="$HOME/.local/scripts"
-source "$scripts/bootstrap/base_functions"
-source "$scripts/bootstrap/mac_functions"
+bootstrap_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DOTFILES_ROOT="$(cd "$bootstrap_dir/../../.." && pwd)"
+export DOTFILES_ROOT
+source "$bootstrap_dir/base_functions"
+source "$bootstrap_dir/mac_functions"
 parse_bootstrap_args "$@"
 configure_dual_boot_utc_rtc
 
 ### INSTALLATION
+brew_install
+bootstrap_stow_checkout mac
 install_preparation
 #app_store_install
-brew_install
 mac_install
 ai_tools_install
 vim_install

.local/scripts/bootstrap/mac_functions

@@ -183,7 +183,7 @@ vim_install () {
     cd "$HOME" || exit
     vim +PlugInstall +qall
     # Vim YouCompleteMe plugin install
-    bash "$HOME/.local/scripts/ycm.sh"
+    bash "${DOTFILES_ROOT:-$HOME}/.local/scripts/ycm.sh"
     sudo npm install -g neovim
     python3 -m pip install --user --upgrade pynvim
     sudo gem install neovim

.local/scripts/bootstrap/manjaro

@@ -5,9 +5,11 @@ set -euo pipefail
 ### WARNING: If this script is to be changed, beware of the order of execution of every command
 
 ### VARIABLES
-scripts="$HOME/.local/scripts"
-source "$scripts/bootstrap/base_functions"
-source "$scripts/bootstrap/arch_functions"
+bootstrap_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DOTFILES_ROOT="$(cd "$bootstrap_dir/../../.." && pwd)"
+export DOTFILES_ROOT
+source "$bootstrap_dir/base_functions"
+source "$bootstrap_dir/arch_functions"
 parse_bootstrap_args "$@"
 configure_dual_boot_utc_rtc
 
@@ -18,6 +20,8 @@ resolve_first_run_choice
 info "Updating system..."
 sudo pacman -Syu
 
+bootstrap_stow_checkout manjaro
+
 install_preparation
 
 echo "#! /bin/sh

.local/scripts/bootstrap/ubuntu

@@ -3,9 +3,11 @@
 set -euo pipefail
 
 ### VARIABLES
-scripts="$HOME/.local/scripts"
-source "$scripts/bootstrap/base_functions"
-source "$scripts/bootstrap/ubuntu_functions"
+bootstrap_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DOTFILES_ROOT="$(cd "$bootstrap_dir/../../.." && pwd)"
+export DOTFILES_ROOT
+source "$bootstrap_dir/base_functions"
+source "$bootstrap_dir/ubuntu_functions"
 parse_bootstrap_args "$@"
 configure_dual_boot_utc_rtc
 
@@ -16,6 +18,8 @@ resolve_first_run_choice
 info "Updating system..."
 sudo apt-get update && sudo apt-get full-upgrade -y
 
+bootstrap_stow_checkout ubuntu
+
 install_preparation
 
 echo "#! /bin/sh

.local/scripts/bootstrap/ubuntu_functions

@@ -2,7 +2,7 @@
 # Author: https://github.com/cuberhaus
 flags="-y"
 apt="sudo apt-get $flags install"
-ycm="$HOME/.local/scripts/ycm.sh" # make sure it's there
+ycm="${DOTFILES_ROOT:-$HOME}/.local/scripts/ycm.sh" # make sure it's there
 scripts="$HOME/.local/scripts"
 
 base_install () {

.local/scripts/bootstrap/ubuntu_windows

@@ -1,18 +1,19 @@
 #! /usr/bin/env bash
 # Author: https://github.com/cuberhaus
 
-### First deploy dotfiles with stow, then execute scripts
-
 ### VARIABLES
-scripts="$HOME/.local/scripts"
+bootstrap_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DOTFILES_ROOT="$(cd "$bootstrap_dir/../../.." && pwd)"
+export DOTFILES_ROOT
 # Include functions
-source "$scripts/bootstrap/ubuntu_functions"
-source "$scripts/bootstrap/base_functions"
+source "$bootstrap_dir/ubuntu_functions"
+source "$bootstrap_dir/base_functions"
 parse_bootstrap_args "$@"
 configure_dual_boot_utc_rtc
 
 ### INSTALLATION
 sudo apt-get update; sudo apt-get full-upgrade  # Update
+bootstrap_stow_checkout ubuntu-windows
 install_preparation
 echo "#! /bin/sh
 export DISTRO=ubuntu_windows" > "$HOME/.config/distro"

.local/scripts/bootstrap/work

@@ -4,16 +4,20 @@
 set -euo pipefail
 
 ### VARIABLES
-scripts="$HOME/.local/scripts"
-source "$scripts/bootstrap/base_functions"
-source "$scripts/bootstrap/work_functions"
+bootstrap_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DOTFILES_ROOT="$(cd "$bootstrap_dir/../../.." && pwd)"
+export DOTFILES_ROOT
+source "$bootstrap_dir/base_functions"
+source "$bootstrap_dir/work_functions"
 parse_bootstrap_args "$@"
 configure_dual_boot_utc_rtc
 
 ### INSTALLATION
 info "Updating system..."
 sudo apt-get update && sudo apt-get full-upgrade -y
 
+bootstrap_stow_checkout work
+
 install_preparation
 
 echo "#! /bin/sh

.local/scripts/bootstrap/work_functions

@@ -9,7 +9,7 @@ apt="sudo apt-get install -y"
 ###############################################################
 
 shutdown_fix() {
-    sudo bash "$HOME/.local/scripts/permanent_shutdown_fix.sh"
+    sudo bash "${DOTFILES_ROOT:-$HOME}/.local/scripts/permanent_shutdown_fix.sh"
 }
 
 ###############################################################

.local/scripts/stow-backup-conflicts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # stow-backup-conflicts — detect stow conflicts and back them up
 #
-# Usage: stow-backup-conflicts [backup-dir]
+# Usage: stow-backup-conflicts [--dry-run] [backup-dir]
 #
 # Runs a stow dry-run, parses conflicts, and moves each conflicting file
 # into a timestamped backup folder.  Exits 0 if there were no conflicts
@@ -25,6 +25,13 @@ TARGET="${HOME}"
 
 BACKUP_ROOT="${1:-$HOME/.dotfiles-backup}"
 BACKUP_DIR="$BACKUP_ROOT/$(date '+%Y-%m-%d_%H%M%S')"
+DRY_RUN=false
+
+if [ "${1:-}" = "--dry-run" ]; then
+    DRY_RUN=true
+    BACKUP_ROOT="${2:-$HOME/.dotfiles-backup}"
+    BACKUP_DIR="$BACKUP_ROOT/$(date '+%Y-%m-%d_%H%M%S')"
+fi
 
 # ---------------------------------------------------------------------------
 # Detect conflicts via stow dry-run
@@ -47,8 +54,12 @@ if (( ${#conflicts[@]} == 0 )); then
     exit 0
 fi
 
-info "Found ${#conflicts[@]} conflict(s). Backing up to $BACKUP_DIR"
-mkdir -p "$BACKUP_DIR"
+if [ "$DRY_RUN" = true ]; then
+    info "Found ${#conflicts[@]} conflict(s). Would back up to $BACKUP_DIR"
+else
+    info "Found ${#conflicts[@]} conflict(s). Backing up to $BACKUP_DIR"
+    mkdir -p "$BACKUP_DIR"
+fi
 
 for rel in "${conflicts[@]}"; do
     src="$TARGET/$rel"
@@ -59,8 +70,17 @@ for rel in "${conflicts[@]}"; do
         continue
     fi
 
+    if [ "$DRY_RUN" = true ]; then
+        info "  Would move $src to $dest"
+        continue
+    fi
+
     mkdir -p "$(dirname "$dest")"
     mv -v "$src" "$dest"
 done
 
-ok "All conflicts backed up to $BACKUP_DIR"
+if [ "$DRY_RUN" = true ]; then
+    ok "No files were moved."
+else
+    ok "All conflicts backed up to $BACKUP_DIR"
+fi