redo is-* commands, redo fs-rm, add dorothy commands

- `dorothy`: add `commands` action, to list the available commands
- `echo-style`: fix `--=` usage causing crash
- `fs-own`: support variant spelling of `recursive` option
- `fs-rm`: redo earlier rewrites to something more robust and intuitive
- `fs-trim`: improve logic
- `gocryptfs-helper`: use `fs-structure`, use `fs-rm --no-confirm-if-empty` to maintain prior behaviour
- `is-broken-symlink`, `is-directory`, `is-empty-directory`, `is-empty-file`, `is-executable`, `is-file`, `is-missing`, `is-nonempty-file`, `is-not-directory`, `is-not-symlink`, `is-present`, `is-readable`, `is-symlink`, `is-writable`: discreet and consistent exit statuses
- promote `is-nonempty-file` from beta to stable
- `mount-helper`: use `fs-rm --no-confirm-if-empty` to maintain prior behaviour
- `setup-util`: use `fs-structure`
- add `setup-util-firefox`
- `ssh-helper`: add `fs-rm --reason` to maintain prior UX consistency
- `eject-all`: use `fs-structure`

commands.beta/convert-helper

@@ -148,7 +148,7 @@ function convert_helper() (
 			outfile="$filename [trimmed].m4a"
 			run ffmpeg -y -i "$path" -af 'silenceremove=stop_periods=-1:stop_duration=0.5:stop_threshold=-60dB' "$outfile"
 			if [[ $option_delete == 'yes' ]]; then
-				fs-rm --no-confirm --quiet -- "$path"
+				fs-rm --quiet --no-confirm -- "$path"
 			fi
 			filename="$filename [trimmed]"
 			path="$outfile"
@@ -199,7 +199,7 @@ function convert_helper() (
 			whisper --model base --language English --output_format srt "$path"
 		fi
 		if [[ $option_delete == 'yes' ]]; then
-			fs-rm --no-confirm --quiet -- "$path"
+			fs-rm --quiet --no-confirm -- "$path"
 		fi
 	done
 )

commands.beta/eject-all

@@ -38,7 +38,7 @@ function eject_all() (
 	echo-style --h1='eject-all'
 
 	echo-style --h2='before'
-	ls /Volumes
+	fs-structure -- /Volumes
 	echo-style --g2='before'
 
 	eval-helper --quiet \
@@ -48,7 +48,7 @@ function eject_all() (
 		-- osascript -e 'tell application "Finder" to eject (every disk whose ejectable is true)'
 
 	echo-style --h2='after'
-	ls /Volumes
+	fs-structure -- /Volumes
 	echo-style --g2='after'
 
 	echo-style --h1='eject-all'

commands/dorothy

@@ -144,6 +144,10 @@ function dorothy_() (
 
 			    Updates Dorothy to the latest version.
 
+			dorothy commands
+
+			    List all the Dorothy commands that are available to you.
+
 			dorothy permissions
 
 			    Correct permissions of new Dorothy commands, ensuring they are executable, and that git is aware of them.
@@ -264,6 +268,9 @@ function dorothy_() (
 		'todo' | 'todos')
 			action='todos'
 			;;
+		'commands')
+			action='commands'
+			;;
 		'--'*) help "An unrecognised flag was provided: $item" ;;
 		*) help "An unrecognised argument was provided: $item" ;;
 		esac
@@ -1533,7 +1540,7 @@ function dorothy_() (
 					DOROTHY_FORCE_LOAD=yes
 					DOROTHY_THEME_OVERRIDE='$theme'
 					. '$DOROTHY/init.sh'
-					echo-style 'Your are now using the ' --invert='$ACTIVE_POSIX_SHELL' ' shell with Dorothy loaded from ' --code='$DOROTHY' \$'\n' 'Use the ' --code='exit' ' command to return to your parent shell.' \$'\n' 'Use ' --code='ls $DOROTHY/commands' ' to see available commands.'
+					echo-style 'Your are now using the ' --invert='$ACTIVE_POSIX_SHELL' ' shell with Dorothy loaded from ' --code='$DOROTHY' \$'\n' 'Use the ' --code='exit' ' command to return to your parent shell.' \$'\n' 'Use ' --code='dorothy commands' ' to see available commands.'
 				EOF
 			)
 			return
@@ -1544,7 +1551,7 @@ function dorothy_() (
 					#!/usr/bin/env nu
 					\$env.DOROTHY_THEME_OVERRIDE = '$theme'
 					source '$DOROTHY/init.nu'
-					echo-style 'Your are now using the ' --invert='nu' ' shell with Dorothy loaded from ' --code='$DOROTHY' "\n" 'Use the ' --code='exit' ' command to return to your parent shell.' "\n" 'Use ' --code='ls $DOROTHY/commands' ' to see available commands.'
+					echo-style 'Your are now using the ' --invert='nu' ' shell with Dorothy loaded from ' --code='$DOROTHY' "\n" 'Use the ' --code='exit' ' command to return to your parent shell.' "\n" 'Use ' --code='dorothy commands' ' to see available commands.'
 				EOF
 			)"
 			return
@@ -1555,7 +1562,7 @@ function dorothy_() (
 					#!/usr/bin/env fish
 					set DOROTHY_THEME_OVERRIDE '$theme'
 					source '$DOROTHY/init.fish'
-					echo-style 'Your are now using the ' --invert='fish' ' shell with Dorothy loaded from ' --code='$DOROTHY' \n 'Use the ' --code='exit' ' command to return to your parent shell.' \n 'Use ' --code='ls $DOROTHY/commands' ' to see available commands.'
+					echo-style 'Your are now using the ' --invert='fish' ' shell with Dorothy loaded from ' --code='$DOROTHY' \n 'Use the ' --code='exit' ' command to return to your parent shell.' \n 'Use ' --code='dorothy commands' ' to see available commands.'
 				EOF
 			)"
 			return
@@ -1597,6 +1604,20 @@ function dorothy_() (
 	# =====================================
 	# Actions: ...
 
+	function act_commands {
+		# pre-requisites
+		assert_dorothy_configured
+
+		local paths=()
+		mapfile -t paths < <(echo-if-present -- "$DOROTHY/commands" "$DOROTHY/commands.beta" "$DOROTHY/user/commands" "$DOROTHY/user/commands.local")
+		setup-util-eza --quiet --optional
+		if __command_exists eza; then
+			eza "${paths[@]}"
+		else
+			ls "${paths[@]}"
+		fi
+	}
+
 	function act_permissions {
 		# pre-requisites
 		assert_dorothy_configured

commands/echo-style

@@ -220,14 +220,14 @@ function echo_style() (
 	}
 	for item in "${items[@]}"; do
 		# check flag status
-		if [[ ${item:0:2} != '--' || $item == '--' || $item == '--=' ]]; then
-			# not a flag, just item content, e.g. 'Hello', '--', '--='
-			buffer_left+="$item"
-			continue
-		elif [[ ${item:0:3} == '--=' ]]; then
-			# empty flag, just item content, e.g. '--=Hello'
+		if [[ ${item:0:3} == '--=' ]]; then
+			# empty flag, just item content, e.g. '--=Hello', --=--=
 			buffer_left+="${item:3}"
 			continue
+		elif [[ ${item:0:2} != '--' || $item == '--' ]]; then
+			# not a flag, just item content, e.g. 'Hello', '--'
+			buffer_left+="$item"
+			continue
 		fi
 		flag="${item:2}"
 		item_content=''

commands/fs-own

@@ -142,7 +142,7 @@ function fs_own() (
 		'--no-optional'* | '--optional'*)
 			option_optional="$(get-flag-value --affirmative --fallback="$option_optional" -- "$item")"
 			;;
-		'--no-recursive'* | '--recursive'*)
+		'--no-recursive'* | '--recursive'* | '--no-recurse'* | '--recurse'* | '--no-recursion'* | '--recursion'*)
 			option_recursive="$(get-flag-value --affirmative --fallback="$option_recursive" -- "$item")"
 			;;
 		'--permissions='*) option_permissions="${item#*=}" ;;
@@ -220,6 +220,7 @@ function fs_own() (
 	# -f: Do not display a diagnostic message when chmod could not modify the mode for file, nor modify the exit status to reflect such (macos)
 	# -f, --silent, --quiet: suppress most error messages (ubuntu)
 	# -R/--recursive: self-explanatory
+	# -h: If the file is a symbolic link, change the mode of the link itself rather than the file that the link points to.
 	local ch_args=()
 	if [[ $option_recursive == 'yes' ]]; then
 		if is-mac || is-alpine; then
@@ -369,6 +370,7 @@ function fs_own() (
 			if [[ ${#sudo_as_user_args[@]} -ne 0 ]]; then
 				cmd+=("${sudo_as_user_args[@]}")
 			fi
+			# removing readable perms on a directory, while recursing, will cause permission denied failure
 			cmd+=(chmod "${ch_args[@]}" "$option_permissions" "${paths[@]}")
 			"${cmd[@]}" # eval
 		fi