aspera-cli 4.27.2 → 4.27.4

data/lib/aspera/cli/command_registry.rb

@@ -11,16 +11,82 @@ module Aspera
     #   register(spec)          - store a CommandSpec; raises on duplicate full_path
     #   register_option(spec)   - store an OptionSpec by name
     #   option_specs            - Hash{Symbol => OptionSpec} of all registered options
-    #   [](path)                - retrieve a CommandSpec by full path
-    #   children_of(path)       - Hash{Symbol => CommandSpec} of direct children (O(1))
-    #   all_paths               - Array of all registered full paths
+    #   [](path)                - retrieve a CommandSpec by full path (follows mounts)
+    #   children_of(path)       - Hash{Symbol => CommandSpec} of direct children (follows mounts)
+    #   resolve(path)           - [registry, path] owning the spec at path (follows mounts)
+    #   local?(path)            - true if path is owned by this registry (not reached through a mount)
+    #   mount_of(path)          - MountSpec of the local node at path, if any
+    #   mount_at(path)          - MountSpec of the node at path, if any (follows mounts)
+    #   own_children_of(path)   - Hash{Symbol => CommandSpec} of direct children declared on the node, without mounted ones
+    #   arguments_at(path)      - Array of ArgumentSpec read by the node at path (mount arguments first)
+    #   leaf_paths              - Array of all leaf paths (follows mounts, or stops at mount nodes)
+    #   command_path(words)     - command path designated by command line words (aliases, arguments)
+    #   all_paths               - Array of all locally registered full paths
     #   any?                    - true if at least one spec has been registered
     #   validate!               - cross-spec consistency checks; raises on violation
+    #
+    # Paths are always expressed in this registry's namespace: a path going through a
+    # mounted node (see MountSpec) is translated to the target registry transparently.
+    # Specs returned for mounted paths are the target's specs (their full_path is in the
+    # target namespace).
     class CommandRegistry
       # @param path [Array<Symbol>] full path to look up
       # @return [CommandSpec, nil]
       def [](path)
-        @specs[Array(path)]
+        registry, local_path = resolve(path)
+        registry.equal?(self) ? @specs[local_path] : registry[local_path]
+      end
+
+      # Find the registry owning `path`, following mounts.
+      # A host child always takes precedence over a mounted child with the same id.
+      # @param path [Array<Symbol>] path in this registry's namespace
+      # @return [Array(CommandRegistry, Array<Symbol>)] owning registry and path in its namespace
+      def resolve(path)
+        path = Array(path)
+        path.each_index do |i|
+          prefix = path[0, i]
+          mount = @specs[prefix]&.mount
+          next if mount.nil? || @children_index[prefix]&.key?(path[i]) || !mount.accepts?(path[i])
+          return mount.registry.resolve(mount.at + path[i..])
+        end
+        [self, path]
+      end
+
+      # @param path [Array<Symbol>] path in this registry's namespace
+      # @return [Boolean] true if the node at path is declared in this registry (not mounted)
+      def local?(path)
+        resolve(path).first.equal?(self)
+      end
+
+      # @param path [Array<Symbol>] local path of a node
+      # @return [MountSpec, nil] the mount declared on that node
+      def mount_of(path)
+        @specs[Array(path)]&.mount
+      end
+
+      # @param path [Array<Symbol>] path in this registry's namespace
+      # @return [MountSpec, nil] the mount declared on the node at path, following mounts
+      def mount_at(path)
+        registry, local_path = resolve(path)
+        registry.mount_of(local_path)
+      end
+
+      # Children declared on the node itself, without the ones exposed by its mount.
+      # @param path [Array<Symbol>] path in this registry's namespace
+      # @return [Hash{Symbol => CommandSpec}]
+      def own_children_of(path)
+        registry, local_path = resolve(path)
+        return registry.own_children_of(local_path) unless registry.equal?(self)
+        @children_index[local_path] || {}
+      end
+
+      # Arguments read by the node at path, in order.
+      # For a child exposed by a mount, the mount's arguments come first (read by the host).
+      # @param path [Array<Symbol>] path in this registry's namespace
+      # @return [Array<ArgumentSpec>]
+      def arguments_at(path)
+        path = Array(path)
+        (path.empty? ? [] : mount_arguments(path)) + (self[path]&.arguments || [])
       end
 
       # Register a CommandSpec. Raises if the full_path is already registered.
@@ -40,14 +106,67 @@ module Aspera
 
       # Returns a Hash mapping each child id to its CommandSpec for all direct
       # children of `path`. Empty hash if no children are registered.
-      # O(1) lookup via the children index built in register().
+      # For a mount node: mounted children (filtered) followed by local children,
+      # local ones overriding mounted ones with the same id.
       # @param path [Array<Symbol>] parent path ([] for root-level commands)
       # @return [Hash{Symbol => CommandSpec}]
       def children_of(path)
-        @children_index[Array(path)] || {}
+        registry, local_path = resolve(path)
+        return registry.children_of(local_path) unless registry.equal?(self)
+        own = @children_index[local_path] || {}
+        mount = @specs[local_path]&.mount
+        return own if mount.nil?
+        mount.registry.children_of(mount.at).select { |id, _| mount.accepts?(id) }.merge(own)
+      end
+
+      # All leaf paths under path, in tree order, following mounts.
+      # A mount cycle (a sub-tree mounting one of its ancestors) is not expanded twice.
+      # @param path          [Array<Symbol>] root of the listing ([] for all)
+      # @param expand_mounts [Boolean]       `false`: a mount node is listed as a leaf, followed by its own children only
+      # @return [Array<Array<Symbol>>]
+      def leaf_paths(path = [], chain = [], expand_mounts: true)
+        children_of(path).keys.flat_map do |id|
+          child = path + [id]
+          key = subtree_key(child)
+          next [] if chain.include?(key)
+          if !expand_mounts && mount_at(child)
+            next [child] + own_children_of(child).keys.flat_map do |own_id|
+              own_child = child + [own_id]
+              children_of(own_child).empty? ? [own_child] : leaf_paths(own_child, chain + [key], expand_mounts: false)
+            end
+          end
+          children_of(child).empty? ? [child] : leaf_paths(child, chain + [key], expand_mounts: expand_mounts)
+        end
       end
 
-      # @return [Array<Array<Symbol>>] all registered full paths
+      # Command path designated by words of a command line: sub-commands (or their aliases),
+      # each possibly followed by its positional arguments, e.g. `packages receive ALL` designates `packages receive`.
+      # Words after a leaf command are its arguments.
+      # @param words [Array<Symbol>] words following the plugin name
+      # @return [Array(Array<Symbol>, Symbol)] command path, and the first word that is neither a sub-command
+      #   nor an expected argument (`nil` if none)
+      def command_path(words)
+        path = []
+        # Number of positional arguments still accepted by the node at path
+        args_left = 0
+        words.each do |word|
+          children = children_of(path)
+          break if children.empty?
+          id = children.key?(word) ? word : children.find { |_, c| Array(c.aliases).include?(word) }&.first
+          if id
+            path += [id]
+            arguments = arguments_at(path)
+            args_left = arguments.any?(&:multiple) ? Float::INFINITY : arguments.length
+          elsif args_left.positive?
+            args_left -= 1
+          else
+            return [path, word]
+          end
+        end
+        [path, nil]
+      end
+
+      # @return [Array<Array<Symbol>>] all locally registered full paths
       def all_paths
         @specs.keys
       end
@@ -77,60 +196,119 @@ module Aspera
       end
 
       # Cross-spec consistency checks.
-      # @param plugin_class [Class, nil] when given, also verify that implicit action methods exist
+      # @param plugin_class [Class, nil] when given, also verify that methods referenced by Symbol
+      #   (implicit and explicit actions, `setup:`, `condition:`, `lookup:`, mount `instance:`) exist
       # @raise [ArgumentError] on any violation
       # @return [self]
       def validate!(plugin_class: nil)
-        # Rule: every non-root parent path that appears in the children index must have
-        # a registered CommandSpec. A missing parent means commands_under(:x) was used
-        # without a matching command :x declaration.
-        @children_index.each_key do |parent_path|
-          next if parent_path.empty? # root is never a CommandSpec
-          unless @specs.key?(parent_path)
+        @children_index.each do |parent_path, children|
+          # Rule: every non-root parent path that appears in the children index must have
+          # a registered CommandSpec. A missing parent means commands_under(:x) was used
+          # without a matching command :x declaration.
+          unless parent_path.empty? || @specs.key?(parent_path)
             raise ArgumentError,
               "commands_under(#{parent_path.map(&:inspect).join(', ')}) used but #{parent_path.last.inspect} has no command declaration"
           end
+          # Rule: an alias designates a single command, and does not hide a sibling command
+          aliases = children.values.flat_map { |c| Array(c.aliases) }
+          conflicts = aliases.select { |a| children.key?(a) || aliases.count(a) > 1 }.uniq
+          raise ArgumentError, "#{parent_path.inspect}: alias conflicts with a sibling command or alias: #{conflicts.inspect}" unless conflicts.empty?
         end
 
         @specs.each_value do |spec|
           path = spec.full_path
 
-          # Rule: delegates_to must point to a known path when present (non-empty array or symbol)
-          if spec.delegates_to
-            dt_path =
-              case spec.delegates_to
-              when Symbol then [spec.delegates_to]
-              when Array  then spec.delegates_to
-              end
-            # An empty array [] means re-enter the root - always valid
-            unless dt_path.empty? || @specs.key?(dt_path)
-              raise ArgumentError,
-                "#{path.inspect}: delegates_to #{dt_path.inspect} points to unknown path"
+          validate_arguments(path, spec.arguments, plugin_class)
+          # Rule: methods called on the plugin instance exist
+          if plugin_class
+            {setup: spec.setup, condition: spec.condition}.each do |attribute, method_name|
+              raise ArgumentError, "#{path.inspect}: no method #{method_name} on #{plugin_class} for #{attribute}:" unless method_name.nil? || instance_method?(plugin_class, method_name)
             end
           end
 
-          # Rule: delegate_instance requires delegates_to
-          if spec.delegate_instance && spec.delegates_to.nil?
-            raise ArgumentError,
-              "#{path.inspect}: delegate_instance requires delegates_to to be set"
+          if (mount = spec.mount)
+            # Rule: a mount needs an instance method, no action, and must point to existing target nodes
+            raise ArgumentError, "#{path.inspect}: mount requires instance:" if mount.instance.nil?
+            # Mount arguments precede the arguments of the mounted command: they cannot be optional
+            raise ArgumentError, "#{path.inspect}: mount arguments must be mandatory" unless mount.arguments.all?(&:mandatory)
+            validate_arguments(path, mount.arguments, plugin_class)
+            raise ArgumentError, "#{path.inspect}: mount and action: are exclusive" if spec.action
+            raise ArgumentError, "#{path.inspect}: mount at #{mount.at.inspect} not found in #{mount.plugin}" unless mount.at.empty? || mount.registry[mount.at]
+            target_ids = mount.registry.children_of(mount.at).keys
+            unknown = Array(mount.only) + Array(mount.except) - target_ids
+            raise ArgumentError, "#{path.inspect}: mount only/except unknown in #{mount.plugin}: #{unknown.inspect}" unless unknown.empty?
+            instance_defined = plugin_class.nil? || instance_method?(plugin_class, mount.instance)
+            raise ArgumentError, "#{path.inspect}: no method #{mount.instance} on #{plugin_class}" unless instance_defined
+            next
           end
 
-          # Rule: leaf commands with no explicit action must have a matching instance method
-          next if spec.action # explicit action: skip
           next if @children_index[path]&.any? # intermediate node: skip
-          next if spec.delegates_to # delegated: skip
-          next unless plugin_class
-          implicit_method = CommandSpec.action_method(path)
-          unless plugin_class.method_defined?(implicit_method) || plugin_class.private_method_defined?(implicit_method)
-            raise ArgumentError,
-              "#{path.inspect}: no action: and no method #{implicit_method} on #{plugin_class}"
+          action = spec.action
+          if action.nil?
+            next unless plugin_class
+            # Rule: leaf commands with no explicit action must have a matching instance method
+            action = CommandSpec.action_method(path)
+            unless instance_method?(plugin_class, action)
+              raise ArgumentError,
+                "#{path.inspect}: no action: and no method #{action} on #{plugin_class}"
+            end
           end
+          action = plugin_class.instance_method(action) if action.is_a?(Symbol) && plugin_class && instance_method?(plugin_class, action)
+          # Rule: the action receives the whole dispatch context as keywords (setup results, arguments),
+          # so it must accept any keyword (`**`): a lambda or method with fixed arity would raise ArgumentError.
+          # A non-lambda Proc ignores extra keywords.
+          next if action.is_a?(Symbol) || (action.is_a?(Proc) && !action.lambda?)
+          raise ArgumentError, "#{path.inspect}: action must accept any keyword (**), parameters: #{action.parameters.inspect}" unless action.parameters.any? { |kind, _| kind.eql?(:keyrest) }
         end
         self
       end
 
       private
 
+      # @return [Boolean] true if plugin_class defines instance method name (public or private)
+      def instance_method?(plugin_class, name)
+        plugin_class.method_defined?(name) || plugin_class.private_method_defined?(name)
+      end
+
+      # Consistency of the positional arguments of a node, in reading order.
+      # @param path         [Array<Symbol>]       node path, for error messages
+      # @param arg_specs    [Array<ArgumentSpec>] arguments of the node (or of its mount)
+      # @param plugin_class [Class, nil]          when given, verify that `lookup:` methods exist
+      # @raise [ArgumentError] on any violation
+      def validate_arguments(path, arg_specs, plugin_class)
+        previous = nil
+        Array(arg_specs).each do |arg|
+          where = "#{path.inspect}: argument #{arg.name}"
+          # Rule: an argument following an optional one, or one that takes all remaining arguments, is never read reliably
+          raise ArgumentError, "#{where}: mandatory after optional #{previous.name}" if previous && arg.mandatory && !previous.mandatory
+          raise ArgumentError, "#{where}: after #{previous.name}, which takes all remaining arguments" if previous&.multiple.eql?(true)
+          unless arg.lookup.nil?
+            # Rule: the percent-selector lookup is only used for identifiers
+            raise ArgumentError, "#{where}: lookup: requires type: :identifier" unless arg.type.eql?(:identifier)
+            raise ArgumentError, "#{where}: no method #{arg.lookup} on #{plugin_class} for lookup:" if arg.lookup.is_a?(Symbol) && plugin_class && !instance_method?(plugin_class, arg.lookup)
+          end
+          previous = arg
+        end
+      end
+
+      # @param path [Array<Symbol>] non-empty path in this registry's namespace
+      # @return [Array<ArgumentSpec>] arguments of the mount exposing the last segment of path, if any
+      def mount_arguments(path)
+        registry, parent = resolve(path[0..-2])
+        return registry.send(:mount_arguments, parent + [path.last]) unless registry.equal?(self)
+        mount = @specs[parent]&.mount
+        return [] if mount.nil? || @children_index[parent]&.key?(path.last) || !mount.accepts?(path.last)
+        mount.arguments
+      end
+
+      # Identity of the sub-tree exposed at path: the mount point for a mount node, else the owning node.
+      # @return [Array(Integer, Array<Symbol>)]
+      def subtree_key(path)
+        registry, local_path = resolve(path)
+        mount = registry.mount_of(local_path)
+        mount ? [mount.registry.object_id, mount.at] : [registry.object_id, local_path]
+      end
+
       def initialize
         # Keyed by Array<Symbol> full path
         @specs = {}

data/lib/aspera/cli/command_spec.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'aspera/schema/registry'
+require 'aspera/cli/option_types'
 
 module Aspera
   module Cli
@@ -10,7 +11,8 @@ module Aspera
     #
     # @!attribute name        [Symbol]                    Name used in help and error messages
     # @!attribute description [String]                    User-facing description
-    # @!attribute type        [Class, Array<Class>, :identifier] Validated type; :identifier triggers instance_identifier
+    # @!attribute type        [Class, Array<Class>, :identifier, nil] Validated type; :identifier triggers instance_identifier.
+    #                                                     Default: String (unless allowed:); explicit nil accepts any value
     # @!attribute mandatory   [Boolean]                   Default true; optional args must come after all mandatory ones
     # @!attribute multiple    [Boolean, String]           true: consume all remaining; String: consume until named marker
     # @!attribute default     [Object, nil]               Default value when mandatory: false and no argument provided
@@ -21,7 +23,7 @@ module Aspera
     #                                                     Proc/lambda → called via instance_exec(field, value, **ctx, &lookup).
     #                                                     Style: use Symbol for named methods; ->(){} for 1-liners; lambda do…end for 2–3 statements.
     # @!attribute allowed     [Array<Symbol>, nil]        Allowed Symbol values; when set, type is forced to Symbol and accept_list is applied
-    # @!attribute interactive [Boolean]                   When true, sets ask_missing_mandatory before resolving so interactive prompting is triggered when no CLI args are provided
+    # @!attribute interactive [Boolean]                   When true, prompts for this argument (only) when no CLI args are provided
     ArgumentSpec = Struct.new(
       :name,
       :description,
@@ -41,8 +43,20 @@ module Aspera
         kwargs[:multiple]     = false if kwargs[:multiple].nil?
         kwargs[:bulk]         = false if kwargs[:bulk].nil?
         kwargs[:interactive]  = false if kwargs[:interactive].nil?
+        kwargs[:type]         = String unless kwargs.key?(:type) || kwargs[:allowed]
         super
       end
+
+      # Syntax of argument for help, e.g. `<name>`, `[<name>]`, `<paths...>`, `<account:Hash>`.
+      # Type is shown only when the argument is not free text.
+      # @return [String]
+      def syntax
+        token = allowed ? allowed.join('|') : name.to_s
+        token += '...' if multiple
+        types = Array(type).grep(Class)
+        token += ":#{types.map(&:name).join('|')}" unless allowed || types.empty? || types.include?(String)
+        mandatory ? "<#{token}>" : "[<#{token}>]"
+      end
     end
 
     # Declares an option referenced by name from command declarations.
@@ -54,11 +68,14 @@ module Aspera
     # @!attribute allowed     [Array, nil]           Allowed values (forwarded to options.declare)
     # @!attribute default     [Object, nil]          Default value
     # @!attribute short       [String, nil]          Single-character short form (e.g. 'x')
-    # @!attribute handler     [Symbol, Hash, nil]
-    #   - Symbol: resolved to {o: <plugin instance>, m: <symbol>} at runtime (Category B)
-    #   - Hash:   {o: <object>, m: <method>} used as-is (Category A: singletons / class constants)
-    #   - nil:    option stores its value locally (no delegation)
-    # @!attribute deprecation [String, nil]          Forwarded to options.declare as deprecation:
+    # @!attribute on_set     [Symbol, Proc, #call, nil] Called with the new value each time the value is set
+    #   (for a flag: called without argument when the flag is found)
+    #   - Symbol: method of the plugin instance
+    #   - Proc:   executed with instance_exec on the plugin instance
+    #   - other:  object responding to `call`, e.g. `Log.instance.method(:level=)`
+    #   - nil:    no callback, the value is read with `get_option`
+    # @!attribute shorthand   [String, nil]          For a `Hash` option: a `String` value is stored as `{shorthand => value}`
+    # @!attribute deprecation [Hash, nil]            Forwarded to options.declare as deprecation: `{last:, message:}`
     # @!attribute schema      [String, nil]          JSON schema name; also derives description when nil
     OptionSpec = Struct.new(
       :name,
@@ -66,43 +83,114 @@ module Aspera
       :allowed,
       :default,
       :short,
-      :handler, # kept as-is: this is the option accessor delegation, not a command action
+      :on_set,
+      :shorthand,
       :deprecation,
       :schema,
       keyword_init: true
-    )
+    ) do
+      # Declare this option on a parser, resolving the `on_set` callback.
+      # @param parser [Parser] Parser to declare the option on
+      # @param target [Object, nil] Object for Symbol and Proc `on_set` callbacks (plugin instance); nil: such callbacks are not bound
+      # @return [void]
+      def declare_on(parser, target: nil)
+        parser.declare(
+          name,
+          description: description,
+          short:       short,
+          allowed:     allowed,
+          default:     default,
+          on_set:      resolved_on_set(target),
+          shorthand:   shorthand,
+          deprecation: deprecation,
+          schema:      schema
+        )
+      end
+
+      private
+
+      # @param target [Object, nil] Object for Symbol and Proc `on_set` callbacks
+      # @return [#call, nil] `on_set` callback for `Parser#declare`
+      def resolved_on_set(target)
+        case on_set
+        when Symbol then target&.method(on_set)
+        when Proc
+          return if target.nil?
+          proc_on_set = on_set
+          ->(*value) { target.instance_exec(*value, &proc_on_set) }
+        else on_set
+        end
+      end
+    end
+
+    # Declares that a command node exposes a sub-tree of another plugin class.
+    # The mounted children appear in the host registry (dispatch, --help, completion)
+    # as if they were declared by the host; host children with the same id take precedence.
+    #
+    # @!attribute plugin   [Class]                Target plugin class (subclass of Plugins::Base)
+    # @!attribute at       [Array<Symbol>]        Path in the target registry whose children are mounted ([] = root)
+    # @!attribute instance [Symbol]               Host instance method called with **ctx, returning the target plugin
+    #                                             instance, or [instance, ctx] where ctx seeds the target dispatch
+    #                                             (it replaces what the setups of `at` and its ancestors would provide)
+    # @!attribute only     [Array<Symbol>, nil]   Restrict mounted children to these ids
+    # @!attribute except   [Array<Symbol>, nil]   Exclude these ids from mounted children
+    # @!attribute arguments [Array<ArgumentSpec>] Arguments read by the host after the mounted command, before its own
+    #                                             arguments; resolved values are passed to `instance`
+    #                                             (e.g. `packages ls <package_id> <path>`)
+    MountSpec = Struct.new(
+      :plugin,
+      :at,
+      :instance,
+      :only,
+      :except,
+      :arguments,
+      keyword_init: true
+    ) do
+      def initialize(**kwargs)
+        kwargs[:at] = Array(kwargs[:at]).freeze
+        kwargs[:arguments] = Array(kwargs[:arguments]).map { |a| a.is_a?(Hash) ? ArgumentSpec.new(**a) : a }.freeze
+        super
+      end
+
+      # @return [CommandRegistry] registry of the target plugin class
+      def registry
+        plugin.command_registry
+      end
+
+      # @param id [Symbol] id of a child of `at` in the target registry
+      # @return [Boolean] true if this child is exposed by the mount
+      def accepts?(id)
+        (only.nil? || only.include?(id)) && !except&.include?(id)
+      end
+    end
 
     # Declares a single command node in the flat registry.
     #
     # @!attribute id               [Symbol]                      Unique identifier within its parent's namespace
     # @!attribute parent           [Symbol, Array<Symbol>, nil]  Full path to parent; nil for root commands
     # @!attribute description      [String]                      User-facing help text
-    # @!attribute options          [Array<Symbol>]               Option names consumed by this command
     # @!attribute arguments        [Array<ArgumentSpec>]         Positional arguments, in order.
     #                                                            The first ArgumentSpec with type: :identifier is treated as the instance
     #                                                            identifier for intermediate nodes (consumed in Phase A) and leaf nodes.
     # @!attribute action           [Symbol, Proc, nil]           Instance method (Symbol) or inline block (Proc) called when this is a leaf command
     # @!attribute setup            [Symbol, nil]                 Instance method called before dispatching to children; returns Hash merged into ctx
-    # @!attribute delegates_to     [Symbol, Array<Symbol>, nil]  Re-enter the command tree at this path
-    # @!attribute delegate_instance [Symbol, nil]                Instance method returning a different plugin object
     # @!attribute aliases          [Array<Symbol>, nil] Alternative names accepted for this command (each resolves to this command's id)
     # @!attribute transfer_paths   [:send, :receive, nil]        File-list resolution delegated to TransferAgent; mutually exclusive with arguments
     # @!attribute condition        [Symbol, nil]                 Instance method returning Boolean; if false command is hidden from dispatch
     # @!attribute query_schema     [String, nil]                 Schema path for --query help; when set, the runner hints `--query=help`
+    # @!attribute mount            [MountSpec, Hash, nil]        Expose children of another plugin's registry under this node
     CommandSpec = Struct.new(
       :id,
       :parent,
       :description,
-      :options,
       :arguments,
       :action,
       :setup,
-      :delegates_to,
-      :delegate_instance,
       :aliases,
       :transfer_paths,
       :condition,
       :query_schema,
+      :mount,
       keyword_init: true
     ) do
       def initialize(**kwargs)
@@ -112,6 +200,7 @@ module Aspera
             a.is_a?(Hash) ? ArgumentSpec.new(**a) : a
           end
         end
+        kwargs[:mount] = MountSpec.new(**kwargs[:mount]) if kwargs[:mount].is_a?(Hash)
         super
       end
 

data/lib/aspera/cli/completion/ascli.bash

@@ -0,0 +1,12 @@
+# Bash completion for ascli
+# Activate: eval "$(ascli config completion bash)"
+
+_ascli_complete() {
+    local cur="${COMP_WORDS[COMP_CWORD]}"
+    # COMP_WORDS[0] is the program name itself; pass only the words typed before the cursor
+    local candidates
+    candidates=$(ascli config completion words "${COMP_WORDS[@]:1:COMP_CWORD-1}" 2>/dev/null)
+    COMPREPLY=( $(compgen -W "${candidates}" -- "${cur}") )
+}
+
+complete -F _ascli_complete ascli

data/lib/aspera/cli/completion/ascli.fish

@@ -0,0 +1,16 @@
+# Fish completion for ascli
+# Activate: ascli config completion fish | source
+# Or save as file ~/.config/fish/completions/ascli.fish
+
+# Remove completions of a previous activation
+complete --command ascli --erase
+
+# Disable file completion entirely — ascli manages its own argument tree
+complete --command ascli --no-files
+
+# Dynamic completion: pass all words already typed (excluding 'ascli' itself)
+# to `ascli config completion words` and return the result as completions.
+complete --command ascli --arguments '(
+    set -l words (commandline -opc)
+    ascli config completion words $words[2..] 2>/dev/null
+)'

data/lib/aspera/cli/completion/ascli.zsh

@@ -0,0 +1,19 @@
+#compdef ascli
+# Zsh completion for ascli
+# Activate (after compinit): eval "$(ascli config completion zsh)"
+# Or save as file `_ascli` in a folder of $fpath
+
+_ascli() {
+    local -a candidates
+    # words[1] is 'ascli' itself; pass only the words typed before the cursor
+    candidates=(${(f)"$(ascli config completion words "${(@)words[2,CURRENT-1]}" 2>/dev/null)"})
+    compadd -a candidates
+}
+
+if [[ "${funcstack[1]}" == _ascli ]]; then
+    # Autoloaded from $fpath: this file is the body of function _ascli
+    _ascli "$@"
+else
+    # Evaluated or sourced
+    compdef _ascli ascli
+fi

data/lib/aspera/cli/context.rb

@@ -36,6 +36,8 @@ module Aspera
       attr_accessor :progress_bar
       # Optional: nil when no PAC script is configured
       attr_accessor :pac_executor
+      # `true` when help is requested (`-h`)
+      attr_accessor :help_requested
 
       # Initialize all members to nil, so that they are defined and can be validated later
       # @return [nil]
@@ -43,6 +45,7 @@ module Aspera
         MEMBERS.each { |i| instance_variable_set(:"@#{i}", nil) }
         @progress_bar = nil
         @pac_executor = nil
+        @help_requested = false
       end
 
       # Validate that all mandatory members are non-nil (detect bootstrap bugs)

data/lib/aspera/cli/deprecation.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'aspera/cli/version'
+require 'aspera/assert'
+
+module Aspera
+  module Cli
+    # Deprecation of a feature (e.g. an option).
+    # @!attribute last    [String] Last released version supporting the feature without deprecation, e.g. `4.25.0`
+    # @!attribute message [String] What to use instead, e.g. `use --out.level`
+    Deprecation = Struct.new(:last, :message, keyword_init: true) do
+      def initialize(**kwargs)
+        super
+        Aspera.assert_type(last, String) { 'deprecation last' }
+        Aspera.assert(Gem::Version.correct?(last) && Gem::Version.new(last) < Gem::Version.new(VERSION)) do
+          "deprecation: last (#{last}) must be a released version, before #{VERSION}"
+        end
+        Aspera.assert_type(message, String) { 'deprecation message' }
+      end
+
+      # @return [String] e.g. `deprecated after 4.25.0: use --out.level`
+      def to_s = "deprecated after #{last}: #{message}"
+
+      class << self
+        # @param value [Deprecation, Hash, nil] Deprecation, or its attributes: `{last:, message:}`
+        # @return [Deprecation, nil]
+        def create(value)
+          case value
+          when nil, Deprecation then value
+          when Hash then new(**value)
+          else Aspera.error_unexpected_value(value.class) { 'deprecation, expect Hash {last:, message:}' }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aspera/cli/extended_value.rb

@@ -12,6 +12,8 @@ require 'base64'
 require 'zlib'
 require 'csv'
 require 'singleton'
+require 'aspera/rainbow'
+using Rainbow
 
 module Aspera
   module Cli
@@ -75,7 +77,7 @@ module Aspera
           case mode
           when '' then $stdin.read
           when 'bin' then $stdin.binmode.read
-          when 'chomp' then $stdin.chomp
+          when 'chomp' then $stdin.read.chomp
           else raise BadArgument, "`stdin` supports only: '', 'bin' or 'chomp'"
           end
         end
@@ -116,10 +118,11 @@ module Aspera
       end
 
       # Update the Regex to match an extended value based on @handlers
+      # Anchored on the whole value (`\A`, `\z`), not on lines: a multi-line value is extended only if it starts with a modifier.
       def update_regex
         handler_regex = "#{MARKER_START}(#{modifiers.join('|')})#{MARKER_END}"
-        @regex_single = Regexp.new("^#{handler_regex}(.*)$", Regexp::MULTILINE)
-        @regex_extend = Regexp.new("^(.*)#{handler_regex}([^#{MARKER_IN_END}]*)#{MARKER_IN_END}(.*)$", Regexp::MULTILINE)
+        @regex_single = Regexp.new("\\A#{handler_regex}(.*)\\z", Regexp::MULTILINE)
+        @regex_extend = Regexp.new("\\A(.*)#{handler_regex}([^#{MARKER_IN_END}]*)#{MARKER_IN_END}(.*)\\z", Regexp::MULTILINE)
       end
 
       public