Add support for captuing --help when using catch_all

examples/render-mandoc/docs/download.1

@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 3.2
 .\"
-.TH "download" "1" "September 2025" "Version 0.1.0" "Sample application"
+.TH "download" "1" "November 2025" "Version 0.1.0" "Sample application"
 .SH NAME
 \f[B]download\f[R] \- Sample application
 .SH SYNOPSIS

examples/render-mandoc/docs/download.md

@@ -1,6 +1,6 @@
 % download(1) Version 0.1.0 | Sample application
 % Lana Lang
-% September 2025
+% November 2025
 
 NAME
 ==================================================

lib/bashly/config_validator.rb

@@ -35,6 +35,7 @@ def assert_catch_all_hash(key, value)
       assert_string "#{key}.label", value['label']
       assert_optional_string "#{key}.help", value['help']
       assert_boolean "#{key}.required", value['required']
+      assert_boolean "#{key}.catch_help", value['catch_help']
     end
 
     def assert_default_command(key, value)

lib/bashly/script/catch_all.rb

@@ -3,7 +3,7 @@ module Script
     class CatchAll
       class << self
         def option_keys
-          @option_keys ||= %i[label help required]
+          @option_keys ||= %i[label help required catch_help]
         end
 
         def from_config(config)
@@ -13,7 +13,7 @@ def from_config(config)
           when String
             { label: config }
           when Hash
-            { label: config['label'], help: config['help'], required: config['required'] }
+            config.transform_keys(&:to_sym).slice(*option_keys)
           else
             {}
           end
@@ -22,11 +22,12 @@ def from_config(config)
         end
       end
 
-      def initialize(label: nil, help: nil, required: false, enabled: true)
+      def initialize(label: nil, help: nil, required: false, catch_help: false, enabled: true)
         @label = label
         @help = help
         @required = required
         @enabled = enabled
+        @catch_help = catch_help
       end
 
       def enabled?
@@ -45,6 +46,10 @@ def required?
         @required
       end
 
+      def catch_help?
+        @catch_help
+      end
+
       def usage_string
         return nil unless enabled?
 

lib/bashly/script/introspection/flags.rb

@@ -16,6 +16,13 @@ def flags
           end
         end
 
+        # Returns true if there is at least one fixed flag (--version / --help)
+        # Root command always has --version and subcommands always have --help
+        # except when it is consumed by catch_all
+        def fixed_flags?
+          root_command? || !catch_all.catch_help?
+        end
+
         # Returns true if this command's flags should be considered as gloal
         # flags, and cascade to subcommands
         def global_flags?

lib/bashly/views/command/fixed_flags_filter.gtx

@@ -12,12 +12,14 @@ if root_command?
   > 
 end
 
-= (short_flag_exist?("-h") ? "--help)" : "--help | -h)").indent(4)
->       long_usage=yes
->       <%= function_name %>_usage
->       exit
->       ;;
-> 
+unless catch_all.catch_help?
+  = (short_flag_exist?("-h") ? "--help)" : "--help | -h)").indent(4)
+  >       long_usage=yes
+  >       <%= function_name %>_usage
+  >       exit
+  >       ;;
+  > 
+end
 
 if global_flags?
   flags.each do |flag|

lib/bashly/views/command/long_usage.gtx

@@ -1,15 +1,7 @@
 = view_marker
 
 > if [[ -n "$long_usage" ]]; then
-options_caption = strings[:options]
-if commands.any? && (public_flags.any? || (flags.any? && Settings.private_reveal_key))
-  options_caption = strings[:global_options]
-end
-
->   printf "%s\n" "{{ options_caption.color(:caption) }}"
->
-= render(:usage_flags).indent 2 if flags.any?
-= render(:usage_fixed_flags).indent 2
+= render(:usage_options).indent 2 if flags.any? || fixed_flags?
 = render(:usage_args).indent 2 if args.any? or catch_all.help
 = render(:usage_environment_variables).indent 2 if environment_variables.any?
 = render(:usage_examples).indent 2 if examples

lib/bashly/views/command/usage_fixed_flags.gtx

@@ -1,13 +1,15 @@
 = view_marker
 
-if short_flag_exist?("-h")
-  > printf "  %s\n" "{{ '--help'.color(:flag) }}"
-else
-  > printf "  %s\n" "{{ '--help, -h'.color(:flag) }}"
-end
+unless catch_all.catch_help?
+  if short_flag_exist?("-h")
+    > printf "  %s\n" "{{ '--help'.color(:flag) }}"
+  else
+    > printf "  %s\n" "{{ '--help, -h'.color(:flag) }}"
+  end
 
-> printf "    {{ strings[:help_flag_text] }}\n"
-> echo
+  > printf "    {{ strings[:help_flag_text] }}\n"
+  > echo
+end
 
 if root_command?
   if short_flag_exist?("-v")

lib/bashly/views/command/usage_options.gtx

@@ -0,0 +1,11 @@
+= view_marker
+
+options_caption = strings[:options]
+if commands.any? && (public_flags.any? || (flags.any? && Settings.private_reveal_key))
+  options_caption = strings[:global_options]
+end
+
+> printf "%s\n" "{{ options_caption.color(:caption) }}"
+>
+= render(:usage_flags) if flags.any?
+= render(:usage_fixed_flags)

schemas/bashly.json

@@ -683,6 +683,11 @@
               "description": "Whether the current argument or flag is required\nhttps://bashly.dev/configuration/command/#catch_all",
               "type": "boolean",
               "default": false
+            },
+            "catch_help": {
+              "description": "Whether to also disable the --help flag and catch it like any other\nhttps://bashly.dev/configuration/command/#catch_all",
+              "type": "boolean",
+              "default": false
             }
           },
           "additionalProperties": false

spec/approvals/fixtures/catch-all-including-help

@@ -0,0 +1,26 @@
++ bundle exec bashly generate
+creating user files in src
+skipped src/docker_command.sh (exists)
+created ./cli
+run ./cli --help to test your bash script
++ ./cli docker --help
+args: none
+
+other_args:
+- ${other_args[*]} = --help
+- ${other_args[0]} = --help
++ ./cli docker --show-help-anyway
+cli docker - Pass all arguments to the docker cli
+
+Usage:
+  cli docker [OPTIONS] [--] [PARAMS...]
+  cli docker --help | -h
+
+Options:
+  --show-help-anyway
+    Show this help message
+
+Arguments:
+  PARAMS...
+    Parameters to pass to docker
+

spec/approvals/fixtures/catch-all-no-fixed-flags

@@ -0,0 +1,22 @@
++ bundle exec bashly generate
+creating user files in src
+skipped src/docker_command.sh (exists)
+created ./cli
+run ./cli --help to test your bash script
++ ./cli docker --help
+args: none
+
+other_args:
+- ${other_args[*]} = --help
+- ${other_args[0]} = --help
++ ./cli docker show-hidden-usage
+cli docker - Pass all arguments to the docker cli
+
+Usage:
+  cli docker [--] [PARAMS...]
+  cli docker --help | -h
+
+Arguments:
+  PARAMS...
+    Parameters to pass to docker
+

spec/approvals/validations/command_catch_all_catch_help

@@ -0,0 +1 @@
+#<Bashly::ConfigurationError: root.catch_all.catch_help must be a boolean>

spec/fixtures/script/validations.yml

@@ -94,6 +94,13 @@
   help: catch_all must be boolean, string, or hash
   catch_all: [1,2]
 
+:command_catch_all_catch_help:
+  name: invalid
+  help: catch_all.catch_help must be boolean
+  catch_all:
+    label: params
+    catch_help: "this is not a help string"
+
 :command_catch_all_valid:
   name: invalid
   catch_all:

spec/fixtures/workspaces/catch-all-including-help/.gitignore

@@ -0,0 +1 @@
+cli

spec/fixtures/workspaces/catch-all-including-help/README.md

@@ -0,0 +1 @@
+This fixture tests that catch all with catch_help is catching the --help flag

spec/fixtures/workspaces/catch-all-including-help/src/bashly.yml

@@ -0,0 +1,18 @@
+name: cli
+help: Showing catch all including the help flag
+version: 0.1.0
+
+commands:
+- name: docker
+  help: Pass all arguments to the docker cli
+  catch_all:
+    label: params
+    help: Parameters to pass to docker
+    required: false
+    # Also catch --help | -h as any other param
+    catch_help: true
+
+  # We want to see that the internal usage command still prints normally
+  flags:
+    - long: --show-help-anyway
+      help: Show this help message

spec/fixtures/workspaces/catch-all-including-help/src/docker_command.sh

@@ -0,0 +1,8 @@
+show_help=${args["--show-help-anyway"]-}
+
+if [[ $show_help ]]; then
+  long_usage=yes
+  cli_docker_usage
+else
+  inspect_args
+fi

spec/fixtures/workspaces/catch-all-including-help/test.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+rm -f ./cli
+
+set -x
+
+bundle exec bashly generate
+
+./cli docker --help
+./cli docker --show-help-anyway

spec/fixtures/workspaces/catch-all-no-fixed-flags/.gitignore

@@ -0,0 +1 @@
+cli

spec/fixtures/workspaces/catch-all-no-fixed-flags/README.md

@@ -0,0 +1,3 @@
+This fixture tests that when catch all is set with catch_help and no other
+flags, the usage text - if called by the developer - is not showing the 
+"Options" caption (since there are now zero options to show)

spec/fixtures/workspaces/catch-all-no-fixed-flags/src/bashly.yml

@@ -0,0 +1,13 @@
+name: cli
+help: Showing catch all including the help flag
+version: 0.1.0
+
+commands:
+- name: docker
+  help: Pass all arguments to the docker cli
+  catch_all:
+    label: params
+    help: Parameters to pass to docker
+    required: false
+    # Also catch --help | -h as any other param
+    catch_help: true

spec/fixtures/workspaces/catch-all-no-fixed-flags/src/docker_command.sh

@@ -0,0 +1,6 @@
+if [[ "${other_args[0]}" == "show-hidden-usage" ]]; then
+  long_usage=yes
+  cli_docker_usage
+else
+  inspect_args
+fi

spec/fixtures/workspaces/catch-all-no-fixed-flags/test.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+rm -f ./cli
+
+set -x
+
+bundle exec bashly generate
+
+./cli docker --help
+./cli docker show-hidden-usage

spec/fixtures/workspaces/lib-upgrade/src/lib/send_completions.sh

@@ -11,24 +11,46 @@ send_completions() {
   echo $'  local cur=${COMP_WORDS[COMP_CWORD]}'
   echo $'  local result=()'
   echo $''
+  echo $'  # words the user already typed (excluding the command itself)'
+  echo $'  local used=()'
+  echo $'  if ((COMP_CWORD > 1)); then'
+  echo $'    used=("${COMP_WORDS[@]:1:$((COMP_CWORD - 1))}")'
+  echo $'  fi'
+  echo $''
   echo $'  if [[ "${cur:0:1}" == "-" ]]; then'
+  echo $'    # Completing an option: offer everything (including options)'
   echo $'    echo "$words"'
   echo $''
   echo $'  else'
+  echo $'    # Completing a non-option: offer only non-options,'
+  echo $'    # and don\'t re-offer ones already used earlier in the line.'
   echo $'    for word in $words; do'
-  echo $'      [[ "${word:0:1}" != "-" ]] && result+=("$word")'
+  echo $'      [[ "${word:0:1}" == "-" ]] && continue'
+  echo $''
+  echo $'      local seen=0'
+  echo $'      for u in "${used[@]}"; do'
+  echo $'        if [[ "$u" == "$word" ]]; then'
+  echo $'          seen=1'
+  echo $'          break'
+  echo $'        fi'
+  echo $'      done'
+  echo $'      ((!seen)) && result+=("$word")'
   echo $'    done'
   echo $''
   echo $'    echo "${result[*]}"'
-  echo $''
   echo $'  fi'
   echo $'}'
   echo $''
   echo $'_cli_completions() {'
   echo $'  local cur=${COMP_WORDS[COMP_CWORD]}'
-  echo $'  local compwords=("${COMP_WORDS[@]:1:$COMP_CWORD-1}")'
+  echo $'  local compwords=()'
+  echo $'  if ((COMP_CWORD > 0)); then'
+  echo $'    compwords=("${COMP_WORDS[@]:1:$((COMP_CWORD - 1))}")'
+  echo $'  fi'
   echo $'  local compline="${compwords[*]}"'
   echo $''
+  echo $'  COMPREPLY=()'
+  echo $''
   echo $'  case "$compline" in'
   echo $'    \'download\'*)'
   echo $'      while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -W "$(_cli_completions_filter "--force --help -f -h")" -- "$cur")'

support/runfile/example.rb

@@ -8,7 +8,9 @@ def examples
     end
 
     def fixtures
-      filter_dirs('spec/fixtures/workspaces').map { |dir| new dir, type: :fixture }
+      filter_dirs('spec/fixtures/workspaces')
+        .select { |dir| File.exist? "#{dir}/src/bashly.yml" }
+        .map { |dir| new dir, type: :fixture }
     end
 
     def all