dorothy: fix dorothy install on fresh macos

this has been a hidden issue for a couple of months, but exemplified by the recent state changes of 8e900c7

/ref https://github.com/bevry/dorothy/actions/runs/7501000504/job/20420777012#step:3:16
/ref 144892e

commands/dorothy

@@ -545,9 +545,7 @@ function dorothy() (
 
 		# ensure state exists
 		mkdir -p "$XDG_STATE_HOME/dorothy"
-		if test ! -L "$DOROTHY/state"; then
-			symlink-helper --quiet --existing="$XDG_STATE_HOME/dorothy" --symlink="$DOROTHY/state"
-		fi
+		relocate_then_symlink_if_necessary "$DOROTHY/state" "$XDG_STATE_HOME/dorothy"
 		mkdir -p "$DOROTHY/state/config.local"
 		mkdir -p "$DOROTHY/state/config"
 		mkdir -p "$DOROTHY/state/sources"
@@ -599,22 +597,48 @@ function dorothy() (
 
 	function relocate_if_necessary {
 		local source="$1" destination="$2"
-		# ensure source exists, and isn't the same as the destination
+		# if source actually exists (is a dir, or a resolvable symlink), we need to merge it with the destination
 		if test -e "$source"; then
-			# ensure we aren't moving to the same location, especially with handling for symlinks, prevents:
-			# mv: /Users/redacted/.local/share/dorothy/user and /Users/redacted/.config/dorothy/user are identical
+			# we are a directory, or a resolvable symlink
+
+			# if a symlink, resolve it
 			if test -L "$source"; then
-				source="$(fs_realpath -- "$source")"
+				source="$(fs_realpath -- "$source")" # only works on resolvable symlinks
 			fi
+
+			# if the destination is a symlink, resolve it or remove it
 			if test -L "$destination"; then
-				destination="$(fs_realpath -- "$destination")"
+				if test ! -e "$destination"; then
+					# not resolvable, remove it
+					rm -f "$destination"
+				else
+					# resolvable, resolve it
+					destination="$(fs_realpath -- "$destination")"
+				fi
 			fi
+
+			# ensure our resolved locations aren't identical
+			# as there is no point moving itself to itself
+			# this prevents this error:
+			# mv: /Users/redacted/.local/share/dorothy/user and /Users/redacted/.config/dorothy/user are identical
 			if test "$source" != "$destination"; then
+				if test -n "$symlink"; then
+					ln -sfF "$destination" "$symlink"
+				fi
 				mv -vf "$source" "$destination"
 			fi
+		elif test -L "$source"; then
+			# source is a broken symlink, remove it
+			rm -f "$source"
 		fi
 	}
 
+	function relocate_then_symlink_if_necessary {
+		local symlink="$1" existing="$2"
+		relocate_if_necessary "$symlink" "$existing"
+		ln -sfF "$existing" "$symlink"
+	}
+
 	function relocate_dorothy_if_necessary {
 		# move if necessary
 		if test -d "$DOROTHY" -o -d "$XDG_DATA_HOME/dorothy"; then
@@ -637,9 +661,8 @@ function dorothy() (
 		# move if necessary
 		if test -d "$DOROTHY/user" -o -d "$XDG_CONFIG_HOME/dorothy"; then
 			if test "$option_xdg" = 'yes'; then
-				relocate_if_necessary "$DOROTHY/user" "$XDG_CONFIG_HOME/dorothy"
 				# ensure $DOROTHY/user always exists
-				symlink-helper --quiet --existing="$XDG_CONFIG_HOME/dorothy" --symlink="$DOROTHY/user"
+				relocate_then_symlink_if_necessary "$DOROTHY/user" "$XDG_CONFIG_HOME/dorothy"
 			elif test "$option_xdg" = 'no'; then
 				relocate_if_necessary "$XDG_CONFIG_HOME/dorothy" "$DOROTHY/user"
 				relocate_if_necessary "$HOME/.config/dorothy" "$DOROTHY/user"

commands/fs-dirname

@@ -80,7 +80,7 @@ function fs_dirname() (
 			cd "$(dirname "$path")"
 			pwd
 		else
-			# the path doesn't exist, so just infer it by trimming the basename
+			# the path doesn't exist (could also be a broken symlink), so just infer it by trimming the basename
 			local basename dirname
 			basename="$(basename "$path")"
 			dirname="${path%"/$basename"}"

commands/fs-realpath

@@ -20,7 +20,7 @@ function fs_realpath() (
 			    Defaults to [--resolve=yes] as it is sensible, and supports macOS without needing GNU or Fish utilities.
 
 			--validate=<YES/no>
-			    If [--validate=yes] require every part of the path to be resolvable, aka do not support broken symlinks.
+			    If [--validate=yes] require every part of the path must be resolvable, aka do not support broken symlinks.
 			    Defaults to [--validate=yes] as it supports macOS without needing GNU or Fish utilities.
 
 			--relative=<NO/yes>

commands/is-missing

@@ -24,7 +24,7 @@ function is_missing() (
 		help 'No <input> provided.'
 	elif test "$*" = '--help'; then
 		help
-	elif test -e "$1" -o -L "$1"; then # just -e is faulty, as -e fails on symlinks
+	elif test -e "$1" -o -L "$1"; then # just -e is faulty, as -e fails on broken symlinks
 		return 1
 	else
 		return 0

commands/is-present

@@ -24,7 +24,7 @@ function is_present() (
 		help 'No <input> provided.'
 	elif test "$*" = '--help'; then
 		help
-	elif test -e "$1" -o -L "$1"; then # just -e is faulty, as -e fails on symlinks
+	elif test -e "$1" -o -L "$1"; then # just -e is faulty, as -e fails on broken symlinks
 		return 0
 	else
 		return 1

commands/setup-util-brew

@@ -11,9 +11,9 @@ function setup_util_brew() (
 	# environment provides:
 	# HOMEBREW_ARCH (macos), HOMEBREW_PREFIX (macosl, linux)
 	if test -z "${HOMEBREW_PREFIX-}"; then
-		echo-error --bold='setup-util-brew: cannot setup brew because HOMEBREW_PREFIX is missing, this oculd be due to:' \
+		echo-error --bold='setup-util-brew: cannot setup brew because HOMEBREW_PREFIX is missing, this could be due to:' \
 			$'\n- homebrew is only supported on macOS and Windows' \
-			$'\n- this command was executed before Dorothy could configure the shell environment, this most likely occured because a Dorothy maintainer invoked a dorothy command within the dorothy instal'
+			$'\n- this command was executed before Dorothy could configure the shell environment, this most likely occured because a Dorothy maintainer invoked a dorothy command within the dorothy install process'
 		return 6 # ENXIO 6 Device not configured
 	fi
 

commands/symlink-helper

@@ -151,6 +151,9 @@ function symlink_helper() (
 	fi
 
 	# create the symlink
+	# -F: replace symlink if directory if needed
+	# -f: unlink symlink path if needed
+	# -s: symbolik link
 	ln -sfF "$option_existing" "$option_symlink"
 
 	# log result to stderr