__do, eval-helper, fs-own, symlink-helper: bugfix

- `bash.bash:__do`:
    - fix `--redirect-stdout`, it was appending the creating FD instead of forwarding to it
- `fs-own`:
    - fix elevation not working
    - support `--changes` on macos (need to test implications on alpine)
    - support `-...` instead of just `--...` (still doesn't support combing `-...`)
    - correctly send `chown`/`chmod` output to STDERR
- `symlink-helper`:
    - ignore broken symlinks if they still point to the intended location
    - colorise formatting on existing symlinks
- `eval-helper`:
    - don't mkdir root home, as it is not necessary (might be different on non-macos envuronments)
    - if needing to make home, perform the normal elevate flow on the home creation, so the user knows why they are being prompted for their password
    - if the home making fails, attempt to continue without home

Author: balupton

commands/eval-helper

@@ -183,7 +183,9 @@ function eval_helper() ( # to use this as a function, it needs to change from a
 			    If a prompt is required to momentarily grant privileges, this reason will be used to explain why elevation was required.
 			--inherit
 			    If enabled, when elevating, the PATH will be inherited to the executing command.
-
+			--home
+			    If disabled, do not ensure the HOME is correct for the elevated user. If the HOME does exist, it will be used.
+			    If the elevate <user> is [root], this will default to disabled.
 		EOF
 		if [[ $# -ne 0 ]]; then
 			echo-error "$@"
@@ -198,7 +200,7 @@ function eval_helper() ( # to use this as a function, it needs to change from a
 	option_terminal_lines='' option_terminal_columns='' \
 	option_confirm='' \
 	option_until='' option_until_interval='' option_until_attempts='' \
-	option_elevated=() option_elevate=() option_user='' option_group='' option_reason='' option_inherit='no' # option_copy_status='' option_redirect_status=''
+	option_elevated=() option_elevate=() option_user='' option_group='' option_reason='' option_inherit='no' option_home='' # option_copy_status='' option_redirect_status=''
 	while [[ $# -ne 0 ]]; do
 		item="$1"
 		shift
@@ -256,6 +258,9 @@ function eval_helper() ( # to use this as a function, it needs to change from a
 		'--no-inherit'* | '--inherit'*)
 			option_inherit="$(get-flag-value --affirmative --fallback="$option_inherit" -- "$item")"
 			;;
+		'--no-home'* | '--home'*)
+			option_home="$(get-flag-value --affirmative --fallback="$option_home" -- "$item")"
+			;;
 		# </elevate>
 		# command
 		'--')
@@ -277,6 +282,15 @@ function eval_helper() ( # to use this as a function, it needs to change from a
 		fi
 	fi
 
+	# home
+	if [[ -z $option_home ]]; then
+		if [[ $option_user == 'root' ]]; then
+			option_home='no'
+		else
+			option_home='yes'
+		fi
+	fi
+
 	# require command
 	if [[ ${#option_cmd[@]} -eq 0 ]]; then
 		help 'No <command> was provided.'
@@ -671,10 +685,17 @@ function eval_helper() ( # to use this as a function, it needs to change from a
 				# ensure home is correctly configured for sudo
 				if [[ -n $home ]]; then
 					if [[ ! -e $home && ! -L $home ]]; then
-						sudo mkdir -p -- "$home" # don't delegate to other commands/functions, as they will call this
-						fs-own --quiet --user="$option_user" --group="$option_group" --no-recursive -- "$home"
+						if [[ $option_home == 'no' ]]; then
+							home='' # root user doesn't need home
+						elif mkdir -p -- "$home" &>/dev/null || eval-helper --elevate --no-home -- mkdir -p -- "$home"; then
+							fs-own --quiet --user="$option_user" --group="$option_group" --no-recursive -- "$home" || :
+						else
+							home=''
+						fi
+					fi
+					if [[ -n $home ]]; then
+						cmd_elevate+=(--set-home)
 					fi
-					cmd_elevate+=(--set-home)
 				fi
 
 				# sudo supports passing environment variables

commands/fs-own

@@ -11,6 +11,9 @@ function fs_own_test() (
 	file="$(fs-temp --root="$root" --file='file' --touch)"
 
 	local flag flags=(
+		--root
+		--admin
+		--me
 		--X
 		--x
 		--r
@@ -20,24 +23,17 @@ function fs_own_test() (
 		--ugx
 		--permissions='a-xrw,ug+Xrw'
 		# --reference="$DOROTHY" <-- on macos this is 40755 which fails when applied to files
-		--me
-		--admin
-		--root
 	)
 	fs-structure -- "$root" "$dir"
 
-	local stderr=''
-	if is-mac; then
-		stderr='Reporting permission changes is not provided by this Operating System.'
-	fi
 	for flag in "${flags[@]}"; do
 		__print_line
-		eval-tester --stderr="$stderr" -- fs-own --no-color --changes "$flag" -- "$dir" "$file"
+		eval-tester --ignore-stderr -- fs-own --no-color --changes "$flag" -- "$dir" "$file"
 		eval-tester -- fs-own --no-color --quiet "$flag" -- "$dir" "$file"
-		eval-tester -- fs-own --no-color --verbose "$flag" -- "$dir" "$file"
-		eval-tester --stderr="$stderr" -- fs-own --no-color --recursive --changes "$flag" -- "$dir"
+		eval-tester --ignore-stderr -- fs-own --no-color --verbose "$flag" -- "$dir" "$file"
+		eval-tester --ignore-stderr -- fs-own --no-color --recursive --changes "$flag" -- "$dir"
 		eval-tester -- fs-own --no-color --recursive --quiet "$flag" -- "$dir"
-		eval-tester -- fs-own --no-color --recursive --verbose "$flag" -- "$dir"
+		eval-tester --ignore-stderr -- fs-own --no-color --recursive --verbose "$flag" -- "$dir"
 		fs-structure -- "$root" "$dir" || :
 	done
 
@@ -62,6 +58,7 @@ function fs_own_test() (
 )
 function fs_own() (
 	source "$DOROTHY/sources/bash.bash"
+	source "$(type -P eval-helper)"
 
 	# =====================================
 	# Arguments
@@ -72,32 +69,31 @@ function fs_own() (
 			Claim ownership of a path, by updating its permissions via chmod and chown.
 
 			USAGE:
-			fs-own [...options] [--] ...<path>
+			fs-own [...options] -- ...<path>
 
 			EXAMPLE:
 			fs-own --recursive --ug -- .
 
 			OPTIONS:
 			--quiet | --verbose | --changes
-			    if --verbose, apply --changes if supported and use --verbose on executed chmod/chown commands.
-			    if --quiet, apply --no-changes
-			    if neither --verbose or --quiet then apply --changes if supported
+			    if [--changes], the default, only output to STDERR the changes
+			    if [--verbose], output to STDERR all operations
 
-			--X
+			--X | -X
 			    sets <permissions> to be executable directories for the user: +x
-			--x
+			--x | -x
 			    sets <permissions> to be executable for the user: +x
-			--r
+			--r | -r
 			    sets <permissions> to be executable for the user: +r
-			--w
+			--w | -w
 			    sets <permissions> to be executable for the user: +w
-			--u
+			--u | -u
 			    sets <permissions> to only be available to the user: a-xrw,u+Xrw
-			--ux
+			--ux | -ux
 			    sets <permissions> to only be available and executable to the user: a-xrw,u+xrw
-			--ug
+			--ug | -ug
 			    sets <permissions> to only be available to the user and group: a-xrw,ug+Xrw
-			--ugx
+			--ugx | -ugx
 			    sets <permissions> to only be available and executable to the user and group: a-xrw,ug+xrw
 			--permissions=<permissions>
 			    sets file and directory permissions.
@@ -204,43 +200,43 @@ function fs_own() (
 			fi
 			option_permissions='+X'
 			;;
-		'--x')
+		'--x' | '-x')
 			if [[ -n $option_permissions ]]; then
 				help "$item cannot be specified with other <permissions>"
 			fi
 			option_permissions='+x'
 			;;
-		'--r')
+		'--r' | '-r')
 			if [[ -n $option_permissions ]]; then
 				help "$item cannot be specified with other <permissions>"
 			fi
 			option_permissions='+r'
 			;;
-		'--w')
+		'--w' | '-w')
 			if [[ -n $option_permissions ]]; then
 				help "$item cannot be specified with other <permissions>"
 			fi
 			option_permissions='+w'
 			;;
-		'--u')
+		'--u' | '-u')
 			if [[ -n $option_permissions ]]; then
 				help "$item cannot be specified with other <permissions>"
 			fi
 			option_permissions='a-xrw,u+Xrw'
 			;;
-		'--ux')
+		'--ux' | '-ux')
 			if [[ -n $option_permissions ]]; then
 				help "$item cannot be specified with other <permissions>"
 			fi
 			option_permissions='a-xrw,u+xrw'
 			;;
-		'--ug')
+		'--ug' | '-ug')
 			if [[ -n $option_permissions ]]; then
 				help "$item cannot be specified with other <permissions>"
 			fi
 			option_permissions='a-xrw,ug+Xrw'
 			;;
-		'--ugx')
+		'--ugx' | '-ugx')
 			if [[ -n $option_permissions ]]; then
 				help "$item cannot be specified with other <permissions>"
 			fi
@@ -264,7 +260,7 @@ function fs_own() (
 			break
 			;;
 		'--'*) help "An unrecognised flag was provided: $item" ;;
-		*) option_paths+=("$item") ;;
+		*) help "An unrecognised argument was provided: $item" ;;
 		esac
 	done
 
@@ -392,32 +388,41 @@ function fs_own() (
 	fi
 
 	# adjustments: changes, quiet, verbose
-	if [[ -z $option_changes ]]; then
-		if [[ $option_quiet == 'yes' ]]; then
-			option_changes='no'
+	function __filter_changes {
+		cat
+	}
+	if [[ $option_quiet == 'no' ]]; then
+		if is-mac; then
+			# Reports even if there are no changes.
+			# -v: Cause chown to be verbose, showing files as the owner is modified.  If the -v flag is specified more than once, chown will print the filename, followed by the old and new numeric user/group ID.
+			# -v: Cause chmod to be verbose, showing filenames as the mode is modified.  If the -v flag is specified more than once, the old and new modes of the file will also be printed, in both octal and symbolic notation.
+			ch_args+=('-vv')
 		else
-			# neither --quiet/--verbose, or just --verbose
-			# in which case, enable changes if supported
-			if is-mac || is-alpine; then
-				option_changes='no'
-			else
-				option_changes='yes'
-			fi
+			# -v, --verbose: output a diagnostic for every file processed
+			ch_args+=('--verbose')
 		fi
-	elif [[ $option_changes == 'yes' ]]; then
+	elif [[ $option_changes != 'no' ]]; then
 		if is-mac || is-alpine; then
-			echo-style --stderr --dim='Reporting permission changes is not provided by this Operating System.'
+			ch_args+=('-vv')
+			function __filter_changes {
+				local line before after
+				while IFS= read -r line; do
+					if [[ $line != *' -> '* ]]; then
+						__print_lines "$line"
+						continue
+					fi
+					before="$(__get_substring_before_last "$line" ' -> ')"
+					after="$(__get_substring_after_last "$line" ' -> ')"
+					before="$(__get_substring_after_last "$before" ': ')"
+					if [[ $before != "$after" ]]; then
+						__print_lines "$line"
+					fi
+				done
+			}
 		else
 			ch_args+=('--changes')
 		fi
 	fi
-	if [[ $option_quiet == 'no' ]]; then
-		if is-mac; then
-			ch_args+=('-v')
-		else
-			ch_args+=('--verbose')
-		fi
-	fi
 
 	# =====================================
 	# Prepare
@@ -443,7 +448,7 @@ function fs_own() (
 		# chown
 		if [[ -n $owner ]]; then
 			# as root
-			eval-helper --elevated="$option_elevated" --elevate="$option_elevated" --reason="$option_reason" -- \
+			eval_helper --redirect-stdout='(__filter_changes)' --redirect-output=STDERR --elevated="$option_elevated" --elevate="$option_elevate" --reason="$option_reason" --user=root -- \
 				chown "${ch_args[@]}" "$owner" "${double_dash_args[@]}" "${paths[@]}" || return # eval
 		fi
 
@@ -452,14 +457,14 @@ function fs_own() (
 			# https://superuser.com/a/91966/32418
 			# removing readable perms on a directory, while recursing, will cause permission denied failure
 			# as user
-			eval-helper --elevated="$option_elevated" --elevate="$option_elevated" --user="$option_user" --group="$option_group" --reason="$option_reason" -- \
+			eval_helper --redirect-stdout='(__filter_changes)' --redirect-output=STDERR --elevated="$option_elevated" --elevate="$option_elevate" --user="$option_user" --group="$option_group" --reason="$option_reason" -- \
 				chmod "${ch_args[@]}" "$option_permissions" "${double_dash_args[@]}" "${paths[@]}" || return # eval
 		fi
 	}
 
 	# determine paths
 	for path in "${option_paths[@]}"; do
-		if is-present --quiet="$option_quiet" --elevated="$option_elevated" --elevate="$option_elevated" --user="$option_user" --group="$option_group" --reason="$option_reason" -- "$path"; then
+		if is-present --quiet="$option_quiet" --elevated="$option_elevated" --elevate="$option_elevate" --user="$option_user" --group="$option_group" --reason="$option_reason" -- "$path"; then
 			paths+=("$path") # it exists, update ownership for it
 		fi
 	done

commands/symlink-helper

@@ -177,26 +177,23 @@ function symlink_helper() (
 		fi
 
 		# check if the symlink is already desired
-		if is-exist --elevated="$option_elevated" --elevate="$option_elevate" --user="$option_user" --group="$option_group" --reason="$option_reason" -- "$symlink_resolved"; then
+		if is-present --elevated="$option_elevated" --elevate="$option_elevate" --user="$option_user" --group="$option_group" --reason="$option_reason" -- "$symlink"; then
 			if [[ $symlink != "$symlink_resolved" ]]; then
 				if [[ $symlink_resolved == "$target_resolved" ]]; then
 					if [[ $option_quiet == 'no' ]]; then
-						echo-style --stderr --bold='👍 Symlink already created at ' --path="$symlink" --bold=' targetting ' --path="$target"
+						echo-style --stderr --note='👍 Symlink already created at ' --path="$symlink" --bold=' targetting ' --path="$target"
 					fi
 					continue
 				fi
 				if [[ -z $option_quiet || $option_quiet == 'no' ]]; then
-					echo-style --stderr --bold='💁‍♀️ Symlink already exists at ' --path="$symlink" ' ' --bold='recreating...'
+					echo-style --stderr --note='💁‍♀️ Symlink already exists at ' --path="$symlink" --bold=' targetting ' --path="$target" ' ' --note='recreating...'
 				fi
 				# is a symlink but a different target, drop it and recreate
 				__wrap rm -f -- "$symlink" >&2
 			else
 				# not a symlink, confirm with the user what to do
 				fs-rm --quiet="$option_quiet" --confirm --elevated="$option_elevated" --elevate="$option_elevate" --user="$option_user" --group="$option_group" --reason="$option_reason" -- "$symlink" >&2
 			fi
-		elif [[ $symlink != "$symlink_resolved" ]]; then
-			# a broken symlink exists at the location, drop it and recreate
-			__wrap rm -f -- "$symlink" >&2
 		else
 			# nothing exists at the location, ensure its parent path at least exists
 			__wrap mkdir -p -- "$(fs-path --parents -- "$symlink")" >&2

sources/bash.bash

@@ -1170,8 +1170,9 @@ function __do {
 
 		# execute while tracking the exit status to our semaphore file
 		# can't use `__try` as >() is a subshell, so the status variable application won't escape the subshell
+		# note [>(...)] and [> >(...)] are different, the former interpolates as a file descriptor, the latter forwards stdout to the file descriptor
 		case "$arg_flag" in
-		--redirect-stdout) __do --right-to-left "$@" >(__do --redirect-status="$semaphore_file_target" -- eval "$code") ;;
+		--redirect-stdout) __do --right-to-left "$@" > >(__do --redirect-status="$semaphore_file_target" -- eval "$code") ;;
 		--redirect-stderr) __do --right-to-left "$@" 2> >(__do --redirect-status="$semaphore_file_target" -- eval "$code") ;;
 		--redirect-output) __do --right-to-left "$@" &> >(__do --redirect-status="$semaphore_file_target" -- eval "$code") ;;
 		*)