feat(commands): Allow --help, -h for all commands (#70)

- Closes #69

.gitignore

@@ -6,3 +6,5 @@ test/tmp/*
 TestResults.xml
 checkver*.html
 *.iso
+/.cache/*
+/.vagrant/*

bin/scoop.ps1

@@ -1,5 +1,5 @@
 #Requires -Version 5
-param($cmd)
+param([string] $cmd)
 
 Set-StrictMode -Off
 
@@ -8,13 +8,36 @@ Set-StrictMode -Off
 }
 
 Reset-Alias
+
 $exitCode = 0
 
-if (('--version' -eq $cmd) -or (!$cmd -and ('-v' -in $args))) {
-    Write-UserMessage -Message 'Current Scoop (soon to be Shovel) version:' -Output
+# Powershell automatically bind bash like short parameters as $args, and does not put it in $cmd parameter
+# ONLY if:
+# - No command passed
+# - -v or --version passed
+$version = ($cmd -eq '--version') -or (!$cmd -and ('-v' -in $args))
+
+# Scoop itself help should be shown only if explicitly asked:
+# - No version asked
+# - No command passed
+# - /?, /help,, /h, --help, -h passed
+$scoopHelp = !$version -and (!$cmd -or (($cmd -in @($null, '--help', '/?', '/help', '/h')) -or (!$cmd -and ('-h' -in $args))))
+
+# Valid command execution
+$validCommand = $cmd -and ($cmd -in (commands))
+
+# Command help should be shown only if:
+# - No help for scoop asked
+# - $cmd is passed
+# - --help, -h is in $args
+$commandHelp = !$scoopHelp -and $validCommand -and (('--help' -in $args) -or ('-h' -in $args))
+
+if ($version) {
+    Write-UserMessage -Message 'Current Scoop (Shovel) version:' -Output
     Invoke-GitCmd -Command 'VersionLog' -Repository (versiondir 'scoop' 'current')
     Write-UserMessage -Message '' -Output
 
+    # TODO: Export to lib/buckets
     Get-LocalBucket | ForEach-Object {
         $b = Find-BucketDirectory $_ -Root
 
@@ -24,11 +47,18 @@ if (('--version' -eq $cmd) -or (!$cmd -and ('-v' -in $args))) {
             Write-UserMessage -Message '' -Output
         }
     }
-} elseif ((@($null, '--help', '/?') -contains $cmd) -or ($args[0] -contains '-h')) {
-    Invoke-ScoopCommand 'help' $args
+} elseif ($scoopHelp) {
+    Invoke-ScoopCommand 'help'
+    $exitCode = $LASTEXITCODE
+} elseif ($commandHelp) {
+    Invoke-ScoopCommand 'help' @{ 'cmd' = $cmd }
     $exitCode = $LASTEXITCODE
-} elseif ((commands) -contains $cmd) {
-    Invoke-ScoopCommand $cmd $args
+} elseif ($validCommand) {
+    # Filter out --help and -h to prevent handling them in each command
+    # This should never be needed, but just in case to prevent failures of installation, etc
+    $newArgs = ($args -notlike '--help') -notlike '-h'
+
+    Invoke-ScoopCommand $cmd $newArgs
     $exitCode = $LASTEXITCODE
 } else {
     Write-UserMessage -Message "scoop: '$cmd' isn't a scoop command. See 'scoop help'." -Output

lib/help.ps1

@@ -11,7 +11,7 @@ function summary($text) {
 }
 
 function scoop_help($text) {
-    $help_lines = $text | Select-String '(?ms)^# Help:(.(?!^[^#]))*' | ForEach-Object { $_.matches[0].Value; }
+    $help_lines = $text | Select-String '(?ms)^# (?:Help|Options):(.(?!^[^#]))*' | ForEach-Object { $_.matches[0].Value; }
     $help_lines -replace '(?ms)^#\s?(Help: )?'
 }
 

libexec/scoop-alias.ps1

@@ -1,4 +1,4 @@
-# Usage: scoop alias [add|list|rm] [<args>]
+# Usage: scoop alias [add|list|rm] [<args>] [options]
 # Summary: Manage scoop aliases
 # Help: Add, remove or list Scoop aliases
 #
@@ -13,7 +13,8 @@
 #     scoop alias add upgrade 'scoop update *' 'Updates all apps, just like brew or apt'
 #
 # Options:
-#   -v, --verbose   Show alias description and table headers (works only for 'list')
+#   -h, --help      Show help for this command.
+#   -v, --verbose   Show alias description and table headers (works only for 'list').
 
 param(
     [String] $Option,

libexec/scoop-bucket.ps1

@@ -1,4 +1,4 @@
-# Usage: scoop bucket [add|list|known|rm] [<args>]
+# Usage: scoop bucket [add|list|known|rm] [<args>] [options]
 # Summary: Manage Scoop buckets
 # Help: Add, list or remove buckets.
 #
@@ -16,6 +16,9 @@
 #   scoop bucket rm versions
 # To list all known buckets, use:
 #   scoop bucket known
+#
+# Options:
+#   -h, --help      Show help for this command.
 
 param($Cmd, $Name, $Repo)
 

libexec/scoop-cache.ps1

@@ -1,4 +1,4 @@
-# Usage: scoop cache [rm|show] [app]
+# Usage: scoop cache [rm|show] [app] [options]
 # Summary: Show or clear the download cache
 # Help: Scoop caches downloads so you don't need to download the same files
 # when you uninstall and re-install the same version of an app.
@@ -11,6 +11,9 @@
 #
 # To clear everything in your cache, use:
 #   scoop cache rm *
+#
+# Options:
+#   -h, --help      Show help for this command.
 
 param($cmd, $app)
 

libexec/scoop-cat.ps1

@@ -1,5 +1,8 @@
-# Usage: scoop cat <apps>
+# Usage: scoop cat <apps> [options]
 # Summary: Show content of specified manifest.
+#
+# Options:
+#   -h, --help      Show help for this command.
 
 param([Parameter(ValueFromRemainingArguments)] [String[]] $Application)
 

libexec/scoop-checkup.ps1

@@ -1,6 +1,9 @@
-# Usage: scoop checkup
+# Usage: scoop checkup [options]
 # Summary: Check for potential problems
 # Help: Performs a series of diagnostic tests to try to identify things that may cause problems with Scoop.
+#
+# Options:
+#   -h, --help      Show help for this command.
 
 'core', 'Diagnostic', 'Helpers' | ForEach-Object {
     . (Join-Path $PSScriptRoot "..\lib\$_.ps1")

libexec/scoop-cleanup.ps1

@@ -6,8 +6,9 @@
 # You can use '*' in place of <app> to cleanup all apps.
 #
 # Options:
-#   -g, --global       Include globally installed apps
-#   -k, --cache        Remove outdated download cache
+#   -h, --help         Show help for this command.
+#   -g, --global       Perform cleanup on globally installed app. (Include them if '*' is used)
+#   -k, --cache        Remove outdated download cache.
 
 'core', 'manifest', 'buckets', 'Versions', 'getopt', 'help', 'install' | ForEach-Object {
     . (Join-Path $PSScriptRoot "..\lib\$_.ps1")

libexec/scoop-config.ps1

@@ -1,4 +1,4 @@
-# Usage: scoop config [rm|show] [name [value]]
+# Usage: scoop config [rm|show] [name [value]] [options]
 # Summary: Get or set configuration values
 # Help: The scoop configuration file is saved at ~/.config/scoop/config.json.
 #
@@ -14,6 +14,9 @@
 # To show full configuration file:
 #   scoop config show
 #
+# Options:
+#   -h, --help      Show help for this command.
+#
 # Settings
 # --------
 #

libexec/scoop-depends.ps1

@@ -1,5 +1,8 @@
-# Usage: scoop depends <app>
+# Usage: scoop depends <app> [options]
 # Summary: List dependencies for an app
+#
+# Options:
+#   -h, --help      Show help for this command.
 
 'depends', 'install', 'manifest', 'buckets', 'getopt', 'decompress', 'help' | ForEach-Object {
     . (Join-Path $PSScriptRoot "..\lib\$_.ps1")

libexec/scoop-download.ps1

@@ -4,6 +4,7 @@
 # Help: All manifest files will be downloaded into cache folder.
 #
 # Options:
+#   -h, --help                      Show help for this command.
 #   -s, --skip                      Skip hash check validation.
 #   -u, --utility <native|aria2>    Force using specific download utility.
 #   -a, --arch <32bit|64bit>        Use the specified architecture.

libexec/scoop-export.ps1

@@ -1,5 +1,8 @@
-# Usage: scoop export > filename
+# Usage: scoop export [options] > filename
 # Summary: Exports (an importable) list of installed apps
+#
+# Options:
+#   -h, --help      Show help for this command.
 
 'core', 'Versions', 'manifest', 'buckets' | ForEach-Object {
     . (Join-Path $PSScriptRoot "..\lib\$_.ps1")

libexec/scoop-help.ps1

@@ -1,5 +1,8 @@
-# Usage: scoop help <command>
+# Usage: scoop help <command> [options]
 # Summary: Show help for a command
+#
+# Options:
+#   -h, --help      Show help for this command.
 
 param($cmd)
 
@@ -35,7 +38,7 @@ if (!($cmd)) {
     print_help $cmd
 } else {
     $exitCode = 3
-    Write-UserMessage -Message "scoop help: no such command '$cmd'"
+    Write-UserMessage -Message "scoop help: no such command '$cmd'" -Output
 }
 
 exit $exitCode

libexec/scoop-hold.ps1

@@ -1,7 +1,8 @@
 # Usage: scoop hold <apps> [options]
 # Summary: Hold an app to disable updates
 # Options:
-#   -g, --global              Hold globally installed app
+#   -h, --help                Show help for this command.
+#   -g, --global              Hold globally installed app.
 
 'getopt', 'help', 'Helpers', 'manifest' | ForEach-Object {
     . (Join-Path $PSScriptRoot "..\lib\$_.ps1")

libexec/scoop-home.ps1

@@ -1,5 +1,8 @@
-# Usage: scoop home <app>
+# Usage: scoop home <app> [options]
 # Summary: Opens the app homepage in default browser
+#
+# Options:
+#   -h, --help      Show help for this command.
 
 param($app)
 

libexec/scoop-info.ps1

@@ -1,5 +1,8 @@
-# Usage: scoop info <app>
+# Usage: scoop info <app> [options]
 # Summary: Display information about an app
+#
+# Options:
+#   -h, --help      Show help for this command.
 
 param($app)
 

libexec/scoop-install.ps1

@@ -11,11 +11,12 @@
 #   scoop install \path\to\app.json
 #
 # Options:
-#   -g, --global              Install the app globally
-#   -i, --independent         Don't install dependencies automatically
-#   -k, --no-cache            Don't use the download cache
-#   -s, --skip                Skip hash validation (use with caution!)
-#   -a, --arch <32bit|64bit>  Use the specified architecture, if the app supports it
+#   -h, --help                Show help for this command.
+#   -g, --global              Install the app globally.
+#   -i, --independent         Don't install dependencies automatically.
+#   -k, --no-cache            Don't use the download cache.
+#   -s, --skip                Skip hash validation (use with caution!).
+#   -a, --arch <32bit|64bit>  Use the specified architecture, if the app supports it.
 
 'Helpers', 'core', 'manifest', 'buckets', 'decompress', 'install', 'shortcuts', 'psmodules', 'Update', 'Versions', 'help', 'getopt', 'depends' | ForEach-Object {
     . (Join-Path $PSScriptRoot "..\lib\$_.ps1")

libexec/scoop-list.ps1

@@ -4,8 +4,9 @@
 # Help: Lists all installed apps, or the apps matching the supplied query.
 #
 # Options:
-#   -i, --installed     List apps sorted by installed date
-#   -u, --updated       List apps sorted by update time
+#   -h, --help          Show help for this command.
+#   -i, --installed     List apps sorted by installed date.
+#   -u, --updated       List apps sorted by update time.
 #   -r, --reverse       Apps will be listed descending order.
 #                           In case of Installed or Updated, apps will be listed from newest to oldest.
 

libexec/scoop-prefix.ps1

@@ -1,5 +1,8 @@
-# Usage: scoop prefix <app>
+# Usage: scoop prefix <app> [options]
 # Summary: Returns the path to the specified app
+#
+# Options:
+#   -h, --help      Show help for this command.
 
 param($app)
 

libexec/scoop-reset.ps1

@@ -1,8 +1,11 @@
-# Usage: scoop reset <app>
+# Usage: scoop reset <app> [options]
 # Summary: Reset an app to resolve conflicts
 # Help: Used to resolve conflicts in favor of a particular app. For example,
 # if you've installed 'python' and 'python27', you can use 'scoop reset' to switch between
 # using one or the other.
+#
+# Options:
+#   -h, --help      Show help for this command.
 
 'core', 'manifest', 'help', 'getopt', 'install', 'Versions', 'shortcuts' | ForEach-Object {
     . (Join-Path $PSScriptRoot "..\lib\$_.ps1")

libexec/scoop-search.ps1

@@ -1,9 +1,12 @@
-# Usage: scoop search <query>
+# Usage: scoop search <query> [options]
 # Summary: Search available apps
 # Help: Searches for apps that are available to install.
 #
 # If used with [query], shows app names that match the query.
 # Without [query], shows all the available apps.
+#
+# Options:
+#   -h, --help      Show help for this command.
 
 param($query)
 

libexec/scoop-status.ps1

@@ -1,5 +1,8 @@
-# Usage: scoop status
+# Usage: scoop status [options]
 # Summary: Show status and check for new app versions
+#
+# Options:
+#   -h, --help      Show help for this command.
 
 'core', 'Helpers', 'manifest', 'buckets', 'Versions', 'depends', 'Git' | ForEach-Object {
     . (Join-Path $PSScriptRoot "..\lib\$_.ps1")

libexec/scoop-unhold.ps1

@@ -1,7 +1,9 @@
 # Usage: scoop unhold <apps> [options]
 # Summary: Unhold an app to enable updates
+#
 # Options:
-#   -g, --global              Unhold globally installed app
+#   -h, --help           Show help for this command.
+#   -g, --global         Unhold globally installed app.
 
 'getopt', 'help', 'Helpers', 'manifest' | ForEach-Object {
     . (Join-Path $PSScriptRoot "..\lib\$_.ps1")

libexec/scoop-uninstall.ps1

@@ -3,8 +3,9 @@
 # Help: e.g. scoop uninstall git
 #
 # Options:
-#   -g, --global   Uninstall a globally installed app
-#   -p, --purge    Remove all persistent data
+#   -h, --help     Show help for this command.
+#   -g, --global   Uninstall a globally installed app.
+#   -p, --purge    Remove all persistent data.
 
 'core', 'manifest', 'help', 'Helpers', 'install', 'shortcuts', 'psmodules', 'versions', 'getopt', 'uninstall' | ForEach-Object {
     . (Join-Path $PSScriptRoot "..\lib\$_.ps1")

libexec/scoop-update.ps1

@@ -6,12 +6,13 @@
 # You can use '*' in place of <app> to update all apps.
 #
 # Options:
-#   -f, --force               Force update even when there isn't a newer version
-#   -g, --global              Update a globally installed app
-#   -i, --independent         Don't install dependencies automatically
-#   -k, --no-cache            Don't use the download cache
-#   -s, --skip                Skip hash validation (use with caution!)
-#   -q, --quiet               Hide extraneous messages
+#   -h, --help                Show help for this command.
+#   -f, --force               Force update even when there isn't a newer version.
+#   -g, --global              Update a globally installed app.
+#   -i, --independent         Don't install dependencies automatically.
+#   -k, --no-cache            Don't use the download cache.
+#   -s, --skip                Skip hash validation (use with caution!).
+#   -q, --quiet               Hide extraneous messages.
 
 'depends', 'Helpers', 'getopt', 'manifest', 'uninstall', 'Update', 'Versions', 'install' | ForEach-Object {
     . (Join-Path $PSScriptRoot "..\lib\$_.ps1")

libexec/scoop-virustotal.ps1

@@ -27,12 +27,13 @@
 #       2 & 4 combined
 #
 # Options:
-#   -a, --arch <32bit|64bit>  Use the specified architecture, if the app supports it
-#   -s, --scan For packages where VirusTotal has no information, send download URL
-#              for analysis (and future retrieval).  This requires you to configure
-#              your virustotal_api_key.
-#   -n, --no-depends By default, all dependencies are checked, too.  This flag allows
-#                    to avoid it.
+#   -h, --help                Show help for this command.
+#   -a, --arch <32bit|64bit>  Use the specified architecture, if the app supports it.
+#   -s, --scan                For packages where VirusTotal has no information, send download URL
+#                             for analysis (and future retrieval). This requires you to configure
+#                             your virustotal_api_key (see help entry for config command).
+#   -n, --no-depends          By default, all dependencies are checked, too.  This flag allows
+#                             to avoid it.
 
 'core', 'depends', 'getopt', 'help', 'VirusTotal' | ForEach-Object {
     . (Join-Path $PSScriptRoot "..\lib\$_.ps1")