aspera-cli 4.26.0 → 4.26.1

data/lib/aspera/schema/documentation.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'aspera/agent/factory'
+require 'aspera/markdown'
+
+module Aspera
+  module Schema
+    # Generate documentation from Schema, for Transfer Spec, or async Conf spec
+    class Documentation
+      # @param formatter [Cli::Formatter] Formatter instance with methods: markdown_text, tick, check_row
+      # @param schema [Reader]
+      # @param include_option [Boolean] `true`: include CLI options (switches, env vars) in descriptions
+      # @param agent_columns  [Boolean] `true`: add separate columns for each transfer agent compatibility
+      # @param code_highlight [Boolean] `true`: format name and type as code
+      def initialize(formatter, schema, include_option: false, agent_columns: false, code_highlight: false)
+        @formatter = formatter
+        @schema = schema
+        @include_option = include_option
+        @agent_columns = agent_columns
+        @code_highlight = code_highlight
+        @columns = %i[name type description]
+        @columns.insert(-2, *Agent::Factory::ALL.values.map{ |i| i[:short]}.sort) if @agent_columns
+        # @type [Array<Hash<Symbol,String>>]
+        @rows = []
+      end
+
+      def rows
+        @rows.sort_by{ |i| i[:name]}
+      end
+
+      # @return [Array<String>]
+      def columns
+        @columns.map(&:to_s)
+      end
+
+      # First row is the titles
+      # @return [Array<Array<String>>]
+      def table
+        [@columns.map(&:to_s)] + @rows.sort_by{ |i| i[:name]}.map{ |row| @columns.map{ |field| row[field]}}
+      end
+
+      # Generate a documentation table from a JSON schema for transfer specifications
+      #
+      # Recursively processes a JSON schema to create a formatted table for manual documentation.
+      # Handles nested objects, arrays, and extracts metadata (descriptions, types, enums, deprecations).
+      #
+      # @param schema [Reader] The JSON schema to process
+      # @return [Documentation]
+      def build(schema = nil)
+        code = @code_highlight ? ->(c){"`#{c}`"} : ->(c){c}
+        schema ||= @schema
+        schema.each_property do |property_schema, _name, property_full_name|
+          node = property_schema.current
+          # Manual table
+          item = {
+            name:        code.call(property_full_name),
+            type:        code.call(node['type']),
+            description: []
+          }
+          # Render Markdown formatting and split lines
+          item[:description] =
+            node['description']
+              .gsub(Markdown::FORMATS){@formatter.markdown_text(Regexp.last_match)}
+              .split("\n") if node.key?('description')
+          item[:description].unshift("DEPRECATED: #{node['x-deprecation']}") if node.key?('x-deprecation')
+          # Add flags for supported agents in doc
+          agents = []
+          Agent::Factory::ALL.each_key do |sym|
+            agents.push(sym) if node['x-agents'].nil? || node['x-agents'].include?(sym.to_s)
+          end
+          Aspera.assert(agents.include?(:direct)){"#{name}: x-cli-option requires agent direct (or nil)"} if node['x-cli-option']
+          if @agent_columns
+            Agent::Factory::ALL.each do |sym, names|
+              item[names[:short]] = @formatter.tick(agents.include?(sym))
+            end
+          else
+            item[:description].push("(#{agents.map{ |i| Agent::Factory::ALL[i][:short].to_s.upcase}.sort.join(', ')})") unless agents.length.eql?(Agent::Factory::ALL.length)
+          end
+          # Only keep lines that are usable in supported agents
+          next false if agents.empty?
+          item[:description].push("Allowed values: #{node['enum'].map{ |v| @formatter.markdown_text("`#{v}`")}.join(', ')}.") if node.key?('enum')
+          item[:description].push("Default: #{code.call(node['default'])}.") if node.key?('default')
+          if @include_option
+            envvar_prefix = ''
+            cli_option =
+              if node.key?('x-cli-envvar')
+                envvar_prefix = 'env:'
+                node['x-cli-envvar']
+              elsif node['x-cli-switch']
+                node['x-cli-option']
+              elsif node['x-cli-option']
+                arg_type = node.key?('enum') ? '{enum}' : "{#{[node['type']].flatten.join('|')}}"
+                # conversion_tag = node['x-cli-convert']
+                conversion_tag = node.key?('x-cli-convert') ? 'conversion' : nil
+                sep = node['x-cli-option'].start_with?('--') ? '=' : ' '
+                "#{node['x-cli-option']}#{sep}#{"(#{conversion_tag})" if conversion_tag}#{arg_type}"
+              end
+            short = node.key?('x-cli-short') ? "(#{node['x-cli-short']})" : nil
+            item[:description].push("(#{'special:' if node['x-cli-special']}#{envvar_prefix}#{@formatter.markdown_text("`#{cli_option}`")})#{short}") if cli_option
+          end
+          @rows.push(@formatter.check_row(item))
+        end
+        self
+      end
+    end
+  end
+end

data/lib/aspera/schema/reader.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Aspera
+  # base class for plugins modules
+  module Schema
+    # JSON schema reader
+    class Reader
+      attr_reader :current
+
+      # Shortcut to access current value at path
+      # @param x [String] path element
+      # @return [Hash, Array, String, Integer] current value at path
+      def [](x)
+        @current[x]
+      end
+
+      # Find sub path relative to current
+      # Honors $ref
+      def dig(*path)
+        current = @current
+        path.each do |p|
+          Aspera.assert(current.key?(p)){"schema: #{p} in #{path}"}
+          current = current[p]
+          Aspera.assert_type(current, Hash){'schema'}
+          if current.key?('$ref')
+            ref = current['$ref']
+            Aspera.assert(ref.start_with?('#/'))
+            current = @root.dig(*ref[2..].split('/'))
+          end
+        end
+        Reader.new(@root, current)
+      end
+
+      # Read schema from file or from cache
+      # @param root [Hash] root schema
+      # @param current [Hash, nil] current position in
+      # @return [Hash, nil] schema
+      def initialize(root, current = nil)
+        @root = root
+        @current = current || root
+      end
+
+      # Recursively traverse schema properties with a block
+      # Handles nested objects and arrays automatically
+      # @param prefix [String] Prefix for property names (e.g., 'parent.child.')
+      # @yield [property_schema, name, full_name] Yields property info to block
+      # @yieldparam property_schema [Reader] Schema reader for this property (use .current to get node hash)
+      # @yieldparam name [String] Property name
+      # @yieldparam full_name [String] Full property name with prefix
+      # @return [nil]
+      def each_property(prefix = '', &block)
+        properties = dig('properties')
+        properties.current.each_key do |name|
+          property_full_name = "#{prefix}#{name}"
+          property_schema = properties.dig(name)
+          node = property_schema.current
+
+          # Yield current property to block
+          yield(property_schema, name, property_full_name)
+
+          # Recursively process nested structures
+          case node['type']
+          when 'object'
+            property_schema.each_property("#{property_full_name}.", &block) if node['properties']
+          when 'array'
+            if node['items']
+              array_item_schema = property_schema.dig('items')
+              array_item_schema.each_property("#{property_full_name}[].", &block) if array_item_schema.current['properties']
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aspera/schema/registry.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'singleton'
+require 'aspera/yaml'
+require 'aspera/schema/reader'
+
+module Aspera
+  # base class for plugins modules
+  module Schema
+    class Registry
+      include Singleton
+
+      class << self
+        def known?(sym)
+          LOCATIONS.key?(sym)
+        end
+
+        def req_body(component, endpoint)
+          "#{component}:paths./#{endpoint}.requestBody.content.application/json.schema"
+        end
+      end
+
+      LOCATIONS = {
+        spec:   'aspera/transfer/spec.schema.yaml',
+        args:   'aspera/sync/args.schema.yaml',
+        conf:   'aspera/sync/conf.schema.yaml',
+        opts:   'aspera/cli/options.schema.yaml',
+        aoc:    'aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml',
+        faspex: 'aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml'
+      }
+
+      OPTIONS = 'opts'
+      TRANSFER_SPEC = 'spec'
+      SYNC_CONF = 'conf'
+      SYNC_ARGS = 'args'
+      AOC = 'aoc'
+      FASPEX = 'faspex'
+      TRANSFER_INFO = "#{OPTIONS}:components.schemas.TransferInfo"
+
+      REQ_BODY = '.requestBody.content.application/json.schema'
+
+      def initialize
+        @cache = {}
+        @main_folder = File.expand_path('../..', __dir__)
+      end
+
+      # Read schema from file or from cache
+      # @param name_path [String] one of the keys in LOCATIONS, with optional :<path> suffix
+      # @return [Reader] schema
+      def reader(name_path)
+        name, path = name_path.split(':', 2)
+        sym = name.to_sym
+        Aspera.assert(Registry.known?(sym)){"schema: #{sym}"}
+        spec_file = File.join(@main_folder, LOCATIONS[sym])
+        @cache[sym] = Yaml.safe_load(File.read(spec_file)) if spec_file.end_with?('.yaml') && !@cache.key?(sym)
+        @cache[sym] = JSON.parse(File.read(spec_file)) if spec_file.end_with?('.json') && !@cache.key?(sym)
+        reader = Reader.new(@cache[sym])
+        return reader unless path
+        reader.dig(*path.split('.'))
+      end
+    end
+  end
+end

data/lib/aspera/sync/conf.schema.yaml

@@ -16,7 +16,6 @@ properties:
   ascp_dir:
     description: Directory containing ascp executable to use.
     type: string
-    default: ""
   assume_no_mods:
     description: Assume that the directory structure has not been modified.
     type: boolean
@@ -52,7 +51,6 @@ properties:
   cookie:
     description: User-defined identification string.
     type: string
-    default: ""
     x-cli-option: true
   cooloff_max_seconds:
     description:
@@ -153,7 +151,6 @@ properties:
       absolute:
         description: UTC timestamp. Empty value for disabled.
         type: string
-        default: ""
       relative_seconds:
         description: Relative to async start time. `-1` for disabled.
         type: integer
@@ -185,7 +182,6 @@ properties:
       pass:
         description: Authenticate the local async with the specified password.
         type: string
-        default: ""
       path:
         description: The directory to be synchronized on the local host.
         type: string
@@ -201,7 +197,6 @@ properties:
     description: Use the specified database directory on the local host.
       Default is `.private-asp` at the root level of the synchronized directory.
     type: string
-    default: ""
     x-cli-option: true
     x-cli-short: -b
   local_checksum_threads:
@@ -215,7 +210,6 @@ properties:
       Store/Restore the database to/from the specified directory on the local host.
       The value can be an absolute path, an URI or - (use the local sync dir)
     type: string
-    default: ""
     x-cli-option: true
   local_force_stat:
     description: Forces the local async to retrieve file information even when no changes are detected by the scanner or monitor.
@@ -233,12 +227,10 @@ properties:
   local_keep_dir:
     description: Move deleted files into the specified directory on the local host.
     type: string
-    default: ""
     x-cli-option: --keep-dir-local
   local_mount_signature:
     description: Verify that the file system is mounted by the existence of this file on the local host.
     type: string
-    default: ""
     x-cli-option: true
   local_move_cache_timeout_seconds:
     description:
@@ -299,13 +291,11 @@ properties:
       local_dir:
         description: Use the specified logging directory on the local host.
         type: string
-        default: ""
         x-cli-option: --alt-logdir
         x-cli-short: -L
       remote_dir:
         description: Use the specified logging directory on the remote host.
         type: string
-        default: ""
         x-cli-option: --remote-logdir
         x-cli-short: -R
   manifest_path:
@@ -313,7 +303,6 @@ properties:
       A directory path where ascp will create manifest TEXT files (passed
       to ascp as --file-manifest-path)
     type: string
-    default: ""
   mirror:
     description:
       Force the pulling side to be exactly like the pushing side, removing
@@ -352,7 +341,6 @@ properties:
     description: Suppress log messages for ITEM.
       The only currently supported ITEM is 'stats', which suppresses both STATS and PROG log messages.
     type: string
-    default: ""
     x-cli-option: true
   no_preserve_root_attrs:
     description: Disable the preservation of attributes on the Sync root.
@@ -455,7 +443,6 @@ properties:
       fingerprint:
         description: Check it against server SSH host key fingerprint.
         type: string
-        default: ""
         x-ts-name: sshfp
       host:
         description: Use the specified host name or address of the remote host.
@@ -465,7 +452,6 @@ properties:
       pass:
         description: Authenticate the transfer with the specified password.
         type: string
-        default: ""
         x-ts-name: remote_password
         x-cli-option: true
         x-cli-short: -w
@@ -516,11 +502,9 @@ properties:
           host:
             description: Use the specified host name or address of the proxy.
             type: string
-            default: ""
           pass:
             description: Authenticate to the proxy with the specified password.
             type: string
-            default: ""
           port:
             description: Use the specified port, default is 9091 for dnat, 9092.
               for dnats
@@ -536,18 +520,15 @@ properties:
           user:
             description: Authenticate to the proxy with the specified username.
             type: string
-            default: ""
       token:
         description: Token string passed to server's authentication service.
         type: string
-        default: ""
         x-ts-name: token
         x-cli-short: -W
       token_node_user:
         description: Node API user identity associated with the token.
           Required for node user bearer tokens
         type: string
-        default: ""
       user:
         description: Authenticate the transfer with the specified username.
         type: string
@@ -563,7 +544,6 @@ properties:
     description: Use the specified database directory on the remote host.
       Default is `.private-asp` at the root level of the synchronized directory.
     type: string
-    default: ""
     x-cli-option: true
     x-cli-short: -B
   remote_db_store_dir:
@@ -571,7 +551,6 @@ properties:
       Store/Restore the database to/from the specified directory on the remote host.
       The value can be an absolute path, an URI or - (use the remote sync dir).
     type: string
-    default: ""
     x-cli-option: true
   remote_force_stat:
     description: Forces the remote async to retrieve file information even when no changes are detected by the scanner or monitor.
@@ -589,12 +568,10 @@ properties:
   remote_keep_dir:
     description: Move deleted files into the specified directory on the remote host.
     type: string
-    default: ""
     x-cli-option: --keep-dir-remote
   remote_mount_signature:
     description: Verify that the file system is mounted by the existence of this file on the remote host.
     type: string
-    default: ""
     x-cli-option: true
   remote_move_cache_timeout_seconds:
     description:
@@ -868,7 +845,6 @@ properties:
       host:
         description: Use the specified host name or address to connect to the datastore.
         type: string
-        default: ""
       port:
         description: Use the specified port.
         type: integer
@@ -876,10 +852,8 @@ properties:
   write_gid:
     description: Try to write files as the specified group.
     type: string
-    default: ""
     x-cli-option: true
   write_uid:
     description: Try to write files as the specified user.
     type: string
-    default: ""
     x-cli-option: true

data/lib/aspera/sync/operations.rb

@@ -9,6 +9,7 @@ require 'aspera/command_line_builder'
 require 'aspera/log'
 require 'aspera/assert'
 require 'aspera/environment'
+require 'aspera/schema/registry'
 require 'json'
 require 'base64'
 require 'open3'
@@ -81,7 +82,10 @@ module Aspera
         # Start the sync process
         # @param sync_info [Hash] Sync parameters, old or new format
         # @param opt_ts    [Hash] Optional transfer spec
-        # @param &block    [nil, Proc] block to generate transfer spec, takes: `direction` (one of DIRECTIONS), `local_dir`, `remote_dir`
+        # @yieldparam direction [Symbol] Sync direction (one of DIRECTIONS: :push, :pull, :bidi)
+        # @yieldparam local_dir [String] Local directory path
+        # @yieldparam remote_dir [String] Remote directory path
+        # @yieldreturn [Hash] Transfer spec to use for authentication
         def start(sync_info, opt_ts = nil)
           Log.dump(:sync_params_initial, sync_info)
           Aspera.assert_type(sync_info, Hash)
@@ -336,10 +340,10 @@ module Aspera
       end
       # Private stuff:
       # Read JSON schema and mapping to command line options
-      ARGS_INSTANCE_SCHEMA = CommandLineBuilder.read_schema(__dir__, 'args')
-      ARGS_SESSION_SCHEMA = ARGS_INSTANCE_SCHEMA['properties']['sessions']['items']
-      ARGS_INSTANCE_SCHEMA['properties'].delete('sessions')
-      CONF_SCHEMA = CommandLineBuilder.read_schema(__dir__, 'conf')
+      ARGS_INSTANCE_SCHEMA = CommandLineBuilder.read_schema(Schema::Registry::SYNC_ARGS)
+      ARGS_SESSION_SCHEMA = ARGS_INSTANCE_SCHEMA.dig(*%w[properties sessions items])
+      ARGS_INSTANCE_SCHEMA.dig('properties').current.delete('sessions')
+      CONF_SCHEMA = CommandLineBuilder.read_schema(Schema::Registry::SYNC_CONF)
       CMDLINE_PARAMS_KEYS = %w[instance sessions].freeze
       ASYNC_ADMIN_EXECUTABLE = 'asyncadmin'
       PRIVATE_FOLDER = "#{Environment.instance.os.eql?(Environment::OS_WINDOWS) ? '~' : '.'}private-asp"

data/lib/aspera/transfer/faux_file.rb

@@ -14,7 +14,7 @@ module Aspera
         # @return nil if not a faux: scheme, else a FauxFile instance
         def create(name)
           return unless name.start_with?(PREFIX)
-          name_params = name[PREFIX.length..-1].split('?', 2)
+          name_params = name.delete_prefix(PREFIX).split('?', 2)
           raise Error, 'Format: #{PREFIX}<file path>?<size>' unless name_params.length.eql?(2)
           raise Error, "Format: <integer>[#{SIZE_UNITS.join(',')}]" unless (m = name_params[1].downcase.match(/^(\d+)([#{SIZE_UNITS.join('')}])$/))
           size = m[1].to_i

data/lib/aspera/transfer/resumer.rb

@@ -32,7 +32,7 @@ module Aspera
       # Calls block a number of times (resumes) until success or limit reached
       # This is re-entrant, one resumer can handle multiple transfers in //
       #
-      # @param block [Proc]
+      # @yieldreturn [void] Executes the transfer operation
       def execute_with_resume
         Aspera.assert(block_given?)
         # maximum of retry

data/lib/aspera/transfer/spec.rb

@@ -50,9 +50,9 @@ module Aspera
           transfer_spec['resume_policy'] = POLICY_FIX[transfer_spec['resume_policy']] if transfer_spec.key?('resume_policy')
         end
       end
-      SCHEMA = CommandLineBuilder.read_schema(__dir__, 'spec', ascp: true)
-      # define constants for enums of parameters: <parameter>_<enum>, e.g. CIPHER_AES_128, DIRECTION_SEND, ...
-      SCHEMA['properties'].each do |name, description|
+      SCHEMA = CommandLineBuilder.read_schema(Schema::Registry::TRANSFER_SPEC, ascp: true)
+      # Define constants for enums of parameters: <parameter>_<enum>, e.g. CIPHER_AES_128, DIRECTION_SEND, ...
+      SCHEMA.current['properties'].each do |name, description|
         next unless description['enum'].is_a?(Array)
         const_set(:"#{name.to_s.upcase}_ENUM_VALUES", description['enum'])
         description['enum'].each do |enum|

data/lib/aspera/transfer/spec.schema.yaml

@@ -8,7 +8,7 @@ $comment: >-
   x-cli-envvar   [String]       Name of env var
   x-cli-option   [String]       Command line option (starts with "-"), or `true`: same as ts, or `false`: not an option
   x-cli-switch   [Boolean]      `true` if option has no arg, else by default option has a value
-  x-cli-special  [Boolean]      `true` if not anaged by command line generator (special handling: option or argument)
+  x-cli-special  [Boolean]      `true` if not managed by command line generator (special handling: option or argument)
   x-cli-convert  [String,Hash]  Method name for Convert object or Conversion Hash for enum: ts to arg
   x-agents       [Array]        Supported agents (for doc only), if not specified: all
   x-deprecation  [String]       Deprecation message for doc

data/lib/aspera/uri_reader.rb

@@ -27,7 +27,7 @@ module Aspera
       # @return [String] the path of a file:// URL
       def file_path(url)
         Aspera.assert(file?(url)){"use format: #{file_url('<path>')}"}
-        File.expand_path(url[SCHEME_FILE_PFX2.length..-1])
+        File.expand_path(url.delete_prefix(SCHEME_FILE_PFX2))
       end
 
       # Read some content from some URI, support file: , http: and https: schemes

data/lib/aspera/yaml.rb

@@ -34,14 +34,16 @@ module Aspera
       duplicate_keys
     end
 
-    # Safely load YAML content, raising an error if duplicate keys are found
+    # Safely load YAML content
+    # raising an error if duplicate keys are found
+    # Validates the yaml, and then call `YAML.safe_load`
     # @param yaml [String] YAML content
     # @return [Object] Parsed YAML content
     # @raise [RuntimeError] If duplicate keys are found
     def safe_load(yaml)
       duplicate_keys = find_duplicate_keys(Psych.parse_stream(yaml))
       raise "Duplicate keys: #{duplicate_keys.join('; ')}" unless duplicate_keys.empty?
-      YAML.safe_load(yaml)
+      YAML.safe_load(yaml, permitted_classes: [Time, Date, Symbol])
     end
 
     module_function :find_duplicate_keys, :safe_load

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: aspera-cli
 version: !ruby/object:Gem::Version
-  version: 4.26.0
+  version: 4.26.1
 platform: ruby
 authors:
 - Laurent Martin
@@ -345,6 +345,7 @@ files:
 - lib/aspera/cli/info.rb
 - lib/aspera/cli/main.rb
 - lib/aspera/cli/manager.rb
+- lib/aspera/cli/options.schema.yaml
 - lib/aspera/cli/plugins/alee.rb
 - lib/aspera/cli/plugins/aoc.rb
 - lib/aspera/cli/plugins/ats.rb
@@ -385,6 +386,7 @@ files:
 - lib/aspera/environment.rb
 - lib/aspera/faspex_gw.rb
 - lib/aspera/faspex_postproc.rb
+- lib/aspera/formatter_interface.rb
 - lib/aspera/hash_ext.rb
 - lib/aspera/id_generator.rb
 - lib/aspera/json_rpc.rb
@@ -425,6 +427,11 @@ files:
 - lib/aspera/rest_error_analyzer.rb
 - lib/aspera/rest_errors_aspera.rb
 - lib/aspera/rest_list.rb
+- lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml
+- lib/aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml
+- lib/aspera/schema/documentation.rb
+- lib/aspera/schema/reader.rb
+- lib/aspera/schema/registry.rb
 - lib/aspera/secret_hider.rb
 - lib/aspera/ssh.rb
 - lib/aspera/ssl.rb
@@ -440,7 +447,6 @@ files:
 - lib/aspera/transfer/resumer.rb
 - lib/aspera/transfer/spec.rb
 - lib/aspera/transfer/spec.schema.yaml
-- lib/aspera/transfer/spec_doc.rb
 - lib/aspera/transfer/uri.rb
 - lib/aspera/uri_reader.rb
 - lib/aspera/web_auth.rb
@@ -473,7 +479,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements:
 - Read the manual for any requirement
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
 summary: 'Execute actions using command line on IBM Aspera Server products: Aspera
   on Cloud, Faspex, Shares, Node, Console, Orchestrator, High Speed Transfer Server'

data/lib/aspera/transfer/spec_doc.rb

@@ -1,76 +0,0 @@
-# frozen_string_literal: true
-
-require 'aspera/agent/factory'
-require 'aspera/markdown'
-
-module Aspera
-  module Transfer
-    # Generate documentation from Schema, for Transfer Spec, or async Conf spec
-    class SpecDoc
-      class << self
-        # @param formatter      [Cli::Formatter] Formatter to use, methods: markdown_text, tick, check_row
-        # @param include_option [Boolean]        `true` : include CLI options
-        # @param agent_columns  [Boolean]        `true` : include agents columns
-        # @param schema         [Hash]           The JSON spec
-        # @return [Array] a table suitable to display in manual
-        def man_table(formatter, include_option: false, agent_columns: true, schema: Spec::SCHEMA)
-          cols = %i[name type description]
-          cols.insert(-2, *Agent::Factory::ALL.values.map{ |i| i[:short]}.sort) if agent_columns
-          rows = []
-          schema['properties'].each do |name, info|
-            rows.concat(man_table(formatter, include_option: include_option, agent_columns: agent_columns, schema: info).last.map{ |h| h.merge(name: "#{name}.#{h[:name]}")}) if info['type'].eql?('object') && info['properties']
-            rows.concat(man_table(formatter, include_option: include_option, agent_columns: agent_columns, schema: info['items']).last.map{ |h| h.merge(name: "#{name}[].#{h[:name]}")}) if info['type'].eql?('array') && info['items'] && info['items']['properties']
-            # Manual table
-            columns = {
-              name:        name,
-              type:        info['type'],
-              description: []
-            }
-            # Render Markdown formatting and split lines
-            columns[:description] =
-              info['description']
-                .gsub(Markdown::FORMATS){formatter.markdown_text(Regexp.last_match)}
-                .split("\n") if info.key?('description')
-            columns[:description].unshift("DEPRECATED: #{info['x-deprecation']}") if info.key?('x-deprecation')
-            # Add flags for supported agents in doc
-            agents = []
-            Agent::Factory::ALL.each_key do |sym|
-              agents.push(sym) if info['x-agents'].nil? || info['x-agents'].include?(sym.to_s)
-            end
-            Aspera.assert(agents.include?(:direct)){"#{name}: x-cli-option requires agent direct (or nil)"} if info['x-cli-option']
-            if agent_columns
-              Agent::Factory::ALL.each do |sym, names|
-                columns[names[:short]] = formatter.tick(agents.include?(sym))
-              end
-            else
-              columns[:description].push("(#{agents.map{ |i| Agent::Factory::ALL[i][:short].to_s.upcase}.sort.join(', ')})") unless agents.length.eql?(Agent::Factory::ALL.length)
-            end
-            # Only keep lines that are usable in supported agents
-            next false if agents.empty?
-            columns[:description].push("Allowed values: #{info['enum'].map{ |v| formatter.markdown_text("`#{v}`")}.join(', ')}") if info.key?('enum')
-            if include_option
-              envvar_prefix = ''
-              cli_option =
-                if info.key?('x-cli-envvar')
-                  envvar_prefix = 'env:'
-                  info['x-cli-envvar']
-                elsif info['x-cli-switch']
-                  info['x-cli-option']
-                elsif info['x-cli-option']
-                  arg_type = info.key?('enum') ? '{enum}' : "{#{[info['type']].flatten.join('|')}}"
-                  # conversion_tag = info['x-cli-convert']
-                  conversion_tag = info.key?('x-cli-convert') ? 'conversion' : nil
-                  sep = info['x-cli-option'].start_with?('--') ? '=' : ' '
-                  "#{info['x-cli-option']}#{sep}#{"(#{conversion_tag})" if conversion_tag}#{arg_type}"
-                end
-              short = info.key?('x-cli-short') ? "(#{info['x-cli-short']})" : nil
-              columns[:description].push("(#{'special:' if info['x-cli-special']}#{envvar_prefix}#{formatter.markdown_text("`#{cli_option}`")})#{short}") if cli_option
-            end
-            rows.push(formatter.check_row(columns))
-          end
-          [cols, rows.sort_by{ |i| i[:name]}]
-        end
-      end
-    end
-  end
-end