aspera-cli 4.26.2 → 4.27.1

data/lib/aspera/cli/http.rb

@@ -4,6 +4,11 @@ require 'aspera/cli/special_values'
 require 'aspera/log'
 require 'aspera/assert'
 require 'aspera/line_logger'
+require 'aspera/schema/registry'
+require 'aspera/cli/option_declarator'
+require 'aspera/rest'
+require 'aspera/oauth'
+require 'aspera/ssl'
 require 'openssl'
 
 module Aspera
@@ -12,6 +17,8 @@ module Aspera
     # Extracted from Plugins::Config so it can be referenced independently
     # via Context#http_config without coupling to the plugin machinery.
     class Http
+      extend OptionDeclarator
+
       # Certificate file extensions recognized when scanning a folder
       CERT_EXT = %w[crt cer pem der].freeze
       # OpenSSL constant that disables peer verification (VERIFY_NONE)
@@ -19,6 +26,13 @@ module Aspera
 
       private_constant :CERT_EXT, :SELF_SIGNED_CERT
 
+      option :insecure,           description: 'HTTP/S: Do not validate any certificate',                   allowed: Type::BOOLEAN, default: false
+      option :ignore_certificate, description: 'HTTP/S: Do not validate certificate for these URLs',        allowed: [Array, NilClass]
+      option :warn_insecure,      description: 'HTTP/S: Issue a warning if certificate is ignored',         allowed: Type::BOOLEAN, default: true
+      option :cert_stores,        description: 'HTTP/S: List of folder with trusted certificates',          allowed: Type::STRING_ARRAY
+      option :http_options,       schema: Schema::Registry::HTTP_OPTIONS
+      option :http_proxy,         description: 'HTTP/S: URL for proxy with optional credentials'
+
       def initialize
         @insecure              = false
         @warn_insecure         = true
@@ -29,19 +43,47 @@ module Aspera
         @certificate_paths     = nil
       end
 
-      attr_accessor :insecure, :warn_insecure, :http_options
-      attr_reader   :ignore_cert_host_port
-
-      # Declare all HTTP/S CLI options, with handlers pointing to self.
-      # Called once from Config#initialize after this object is instantiated.
-      # @param options [Aspera::Cli::Manager]
-      def declare_options(options)
-        options.declare(:insecure, 'HTTP/S: Do not validate any certificate', allowed: Allowed::TYPES_BOOLEAN, handler: {o: self, m: :insecure}, default: false)
-        options.declare(:ignore_certificate, 'HTTP/S: Do not validate certificate for these URLs', allowed: [Array, NilClass], handler: {o: self, m: :ignore_cert_host_port})
-        options.declare(:warn_insecure, 'HTTP/S: Issue a warning if certificate is ignored', allowed: Allowed::TYPES_BOOLEAN, handler: {o: self, m: :warn_insecure}, default: true)
-        options.declare(:cert_stores, 'HTTP/S: List of folder with trusted certificates', allowed: Allowed::TYPES_STRING_ARRAY, handler: {o: self, m: :trusted_cert_locations})
-        options.declare(:http_options, 'HTTP/S: Options for HTTP/S socket', allowed: Hash, handler: {o: self, m: :http_options}, default: {})
-        options.declare(:http_proxy, 'HTTP/S: URL for proxy with optional credentials', handler: {o: self, m: :http_proxy})
+      attr_accessor :insecure, :warn_insecure
+      attr_reader   :ignore_cert_host_port, :http_options
+
+      # Bind all HTTP options to this instance using set_handler.
+      # Called from Config#initialize immediately after Http.new.
+      # @param options [Aspera::Cli::Parser]
+      # @return [nil]
+      def bind_options(options)
+        options.set_handler(:insecure,           object: self, method: :insecure)
+        options.set_handler(:ignore_certificate, object: self, method: :ignore_cert_host_port)
+        options.set_handler(:warn_insecure,      object: self, method: :warn_insecure)
+        options.set_handler(:cert_stores,        object: self, method: :trusted_cert_locations)
+        options.set_handler(:http_options,       object: self, method: :http_options)
+        options.set_handler(:http_proxy,         object: self, method: :http_proxy)
+      end
+
+      # Setter for http_options: dispatch each key to its target singleton immediately.
+      # Keys matching RestParameters setters go to RestParameters, 'ssl_options' goes to SSL,
+      # keys matching OAuth::Factory.instance.parameters go to OAuth, and the rest are kept
+      # in @http_options for Net::HTTP session configuration in update_session.
+      # This runs on every assignment (JSON hash, dotted notation, preset merge) so timing
+      # of option parsing never matters.
+      # @param new_options [Hash] merged http_options hash
+      # @return [nil]
+      def http_options=(new_options)
+        Aspera.assert_type(new_options, Hash)
+        kept = {}
+        new_options.each do |k, v|
+          method = "#{k}=".to_sym
+          if RestParameters.instance.respond_to?(method)
+            RestParameters.instance.send(method, v)
+          elsif k.to_s.eql?('ssl_options')
+            Aspera::SSL.option_list = v
+          elsif OAuth::Factory.instance.parameters.key?(k.to_sym)
+            OAuth::Factory.instance.parameters[k.to_sym] = v
+          else
+            kept[k] = v
+          end
+        end
+        @http_options = kept
+        nil
       end
 
       # ------------------------------------------------------------------
@@ -64,7 +106,7 @@ module Aspera
       def ignore_cert_host_port=(url_list)
         url_list.each do |url|
           uri = URI.parse(url)
-          raise "Expecting https scheme: #{url}" unless uri.scheme.eql?('https')
+          Aspera.assert(uri.scheme.eql?('https')) { "Expecting https scheme: #{url}" }
           @ignore_cert_host_port.push([uri.host, uri.port].freeze)
         end
       end
@@ -77,11 +119,11 @@ module Aspera
         if ignore_cert && @warn_insecure
           base_url = "https://#{address}:#{port}"
           unless @ssl_warned_urls.include?(base_url)
-            Log.log.warn{"Ignoring certificate for: #{base_url}. Do not deactivate certificate verification in production."}
+            Log.log.warn { "Ignoring certificate for: #{base_url}. Do not deactivate certificate verification in production." }
             @ssl_warned_urls.push(base_url)
           end
         end
-        Log.log.debug{"ignore cert? #{endpoint} -> #{ignore_cert}"}
+        Log.log.debug { "ignore cert? #{endpoint} -> #{ignore_cert}" }
         ignore_cert
       end
 
@@ -90,23 +132,24 @@ module Aspera
       # ------------------------------------------------------------------
 
       # Add files, folders or the default OS locations to the cert store.
-      # @param path_list [Array<String>]
+      # @param path_list [Array<String>] list of file/folder paths to add to the certificate store
+      # @return [nil]
       def trusted_cert_locations=(path_list)
-        Aspera.assert_type(path_list, Array){'cert locations'}
+        Aspera.assert_type(path_list, Array) { 'cert locations' }
         if @certificate_store.nil?
           Log.log.debug('Creating SSL Cert store')
           @certificate_store = OpenSSL::X509::Store.new
           @certificate_paths = []
         end
         path_list.each do |path|
-          Aspera.assert_type(path, String){'Expecting a String for certificate location'}
+          Aspera.assert_type(path, String) { 'Expecting a String for certificate location' }
           paths_to_add = [path]
-          Log.log.debug{"Adding cert location: #{path}"}
+          Log.log.debug { "Adding cert location: #{path}" }
           if path.eql?(SpecialValues::DEF)
             @certificate_store.set_default_paths
             paths_to_add = [OpenSSL::X509::DEFAULT_CERT_DIR]
             paths_to_add.push(OpenSSL::X509::DEFAULT_CERT_FILE) unless defined?(JRUBY_VERSION)
-            paths_to_add.select!{ |f| File.exist?(f)}
+            paths_to_add.select! { |f| File.exist?(f) }
           elsif File.file?(path)
             @certificate_store.add_file(path)
           elsif File.directory?(path)
@@ -118,14 +161,15 @@ module Aspera
             pp = [File.realpath(p)]
             if File.directory?(p)
               pp = Dir.entries(p)
-                .map{ |e| File.realpath(File.join(p, e))}
-                .select{ |entry| File.file?(entry)}
-                .select{ |entry| CERT_EXT.any?{ |ext| entry.end_with?(ext)}}
+                .map { |e| File.realpath(File.join(p, e)) }
+                .select { |entry| File.file?(entry) }
+                .select { |entry| CERT_EXT.any? { |ext| entry.end_with?(ext) } }
             end
             @certificate_paths.concat(pp)
           end
         end
         @certificate_paths.uniq!
+        nil
       end
 
       # Return cert file paths (computes OS defaults lazily if never set).
@@ -145,22 +189,22 @@ module Aspera
       # Called every time a new Net::HTTP session is opened.
       # ------------------------------------------------------------------
 
-      # @param http_session [Net::HTTP]
+      # @param http_session [Net::HTTP] HTTP session to configure
+      # @return [nil]
       def update_session(http_session)
         http_session.set_debug_output(LineLogger.new(:trace2)) if Log.instance.logger.trace2?
-        if http_session.use_ssl? && ignore_cert?(http_session.address, http_session.port)
-          http_session.verify_mode = SELF_SIGNED_CERT
-        end
+        http_session.verify_mode = SELF_SIGNED_CERT if http_session.use_ssl? && ignore_cert?(http_session.address, http_session.port)
         http_session.cert_store = @certificate_store if @certificate_store
-        Log.log.debug{"Using cert store #{http_session.cert_store} (#{@certificate_store})"} unless http_session.cert_store.nil?
+        Log.log.debug { "Using cert store #{http_session.cert_store} (#{@certificate_store})" } unless http_session.cert_store.nil?
         @http_options.each do |k, v|
           method = "#{k}=".to_sym
           if http_session.respond_to?(method)
             http_session.send(method, v)
           else
-            Log.log.error{"Unknown HTTP session attribute: #{k}"}
+            Log.log.error { "Unknown HTTP session attribute: #{k}" }
           end
         end
+        nil
       end
     end
   end

data/lib/aspera/cli/info.rb

@@ -15,6 +15,8 @@ module Aspera
       # Set this to warn in advance when minimum required ruby version will increase
       # See also required_ruby_version in gemspec file
       RUBY_FUTURE_MINIMUM_VERSION = '3.2'
+      # Version with which this version of CLI was tested
+      SDK_VERSION = '1.1.9'
     end
   end
 end

data/lib/aspera/cli/mailer.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'aspera/environment'
+require 'aspera/log'
+require 'aspera/assert'
+require 'erb'
+
+module Aspera
+  module Cli
+    # Email service injected into Context as :mailer so that any component
+    # (TransferAgent, plugins, ...) can send emails via SMTP and ERB templates.
+    # Provides :smtp, :notify_to, :notify_template options via the Options manager.
+    class Mailer
+      SMTP_CONF_PARAMS = %i[server tls ssl port domain username password from_name from_email].freeze
+      SMTP_BOOL_PARAMS = %i[tls ssl].freeze
+      SMTP_INT_PARAMS  = %i[port].freeze
+      SMTP_STR_PARAMS  = %i[server domain username password from_email from_name].freeze
+
+      # @param options     [Parser]  CLI options manager (provides :smtp, :notify_to, :notify_template)
+      # @param main_folder [String]   application main folder (unused directly but kept for symmetry)
+      def initialize(options, main_folder)
+        @options     = options
+        @main_folder = main_folder
+      end
+
+      # @return [Parser]
+      attr_reader :options
+
+      # @return [Hash] email server settings with defaults applied
+      def email_settings
+        smtp = options.get_option(:smtp, mandatory: true)
+        # Change keys from string into symbol
+        smtp = smtp.symbolize_keys
+        unsupported = smtp.keys - SMTP_CONF_PARAMS
+        Aspera.assert(unsupported.empty?, type: Cli::Error) { "Unsupported SMTP parameter: #{unsupported.join(', ')}, use: #{SMTP_CONF_PARAMS.join(', ')}" }
+        # Boolean fields must be actual booleans, not strings like "false"
+        SMTP_BOOL_PARAMS.each do |k|
+          Aspera.assert_values(smtp[k], [true, false], type: Cli::Error) { "smtp.#{k}" } if smtp.key?(k)
+        end
+        SMTP_INT_PARAMS.each do |k|
+          Aspera.assert_type(smtp[k], Integer, type: Cli::Error) { "smtp.#{k}" } if smtp.key?(k)
+        end
+        SMTP_STR_PARAMS.each do |k|
+          Aspera.assert_type(smtp[k], String, type: Cli::Error) { "smtp.#{k}" } if smtp.key?(k)
+        end
+        # smtp[:ssl] = nil (false)
+        smtp[:tls] = !smtp[:ssl] unless smtp.key?(:tls)
+        smtp[:port] ||= if smtp[:tls]
+          587
+        elsif smtp[:ssl]
+          465
+        else
+          25
+        end
+        smtp[:from_email] ||= smtp[:username] if smtp.key?(:username)
+        smtp[:from_name] ||= smtp[:from_email].sub(/@.*$/, '').gsub(/[^a-zA-Z]/, ' ').capitalize if smtp.key?(:username)
+        smtp[:domain] ||= smtp[:from_email].sub(/^.*@/, '') if smtp.key?(:from_email)
+        %i[server port domain].each do |n|
+          Aspera.assert(smtp.key?(n)) { "Missing mandatory smtp parameter: #{n}" }
+        end
+        Log.dump(:smtp, smtp.reject { |k, _| k == :password })
+        return smtp
+      end
+
+      # Send email using ERB template
+      # @param email_template_default [String] default template, can be overridden by option
+      # @param values [Hash] values to be used in template, keys with default: to, from_name, from_email
+      def send_email_template(email_template_default: nil, values: {})
+        values[:to] ||= options.get_option(:notify_to, mandatory: true)
+        notify_template = options.get_option(:notify_template, mandatory: email_template_default.nil?) || email_template_default
+        mail_conf = email_settings
+        values[:from_name] ||= mail_conf[:from_name]
+        values[:from_email] ||= mail_conf[:from_email]
+        %i[to from_email].each do |n|
+          Aspera.assert_type(values[n], String) { "Missing email parameter: #{n} in config" }
+        end
+        start_options = [mail_conf[:domain]]
+        start_options.push(mail_conf[:username], mail_conf[:password], :login) if mail_conf.key?(:username) && mail_conf.key?(:password)
+        template_binding = Environment.empty_binding
+        values.each do |k, v|
+          Aspera.assert_type(k, Symbol)
+          template_binding.local_variable_set(k, v)
+        end
+        msg_with_headers = ERB.new(notify_template).result(template_binding)
+        Log.dump(:msg_with_headers, msg_with_headers)
+        require 'net/smtp'
+        smtp = Net::SMTP.new(mail_conf[:server], mail_conf[:port])
+        smtp.enable_starttls if mail_conf[:tls]
+        smtp.enable_tls if mail_conf[:ssl]
+        smtp.start(*start_options) do |smtp_session|
+          smtp_session.send_message(msg_with_headers, values[:from_email], values[:to])
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/aspera/cli/mcp_tool.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+# cspell:ignore ascli
+
+require 'json'
+require 'aspera/log'
+require 'aspera/cli/runner'
+require 'aspera/cli/error'
+require 'aspera/schema/reader'
+require 'aspera/schema/registry'
+unless defined?(MCP::Tool)
+  begin
+    require 'mcp'
+  rescue LoadError
+    raise Cli::Error, "The 'mcp' and 'rack' gems are required. Install them with: gem install mcp rack"
+  end
+end
+
+module Aspera
+  module Cli
+    # MCP Tool: executes an ascli command in-process.
+    class McpTool < MCP::Tool
+      # Default maximum byte size of the JSON text content returned for list results.
+      # Items are appended whole until the limit is reached; the full list is always
+      # available in structuredContent.
+      DEFAULT_MAX_TEXT_BYTES = 100_000
+      # Default extra arguments automatically prepended to every ascli call.
+      # Keeps the AI from having to remember mandatory flags on every invocation.
+      DEFAULT_EXTRA_ARGS = ['--interactive=no', '--transfer.asynchronous=true'].freeze
+
+      tool_name 'execute_ascli_command'
+
+      description <<~DESC.strip
+        Execute any ascli (Aspera CLI) command in-process and return its result.
+
+        SYNTAX
+          args is a JSON array of strings mirroring the CLI command line.
+          Element 0 : plugin name (aoc, faspex5, node, server, config, …).
+          Elements 1+: sub-commands, then --option=value flags in any order.
+          Passing structured values: use an extended-value prefix on the relevant element:
+            "@json:{...}"   — inline JSON object or array (preferred for LLMs: no shell quoting, natural JSON)
+            "@preset:name"  — expand a saved credential preset
+            "@env:VAR"      — read value from environment variable
+            "@file:/path"   — read value from a file
+          Note: the dot-path form (@: key=value ...) is designed for humans typing in a terminal shell.
+          Prefer @json: when building args programmatically or as an LLM.
+
+        AUTOMATIC FLAGS
+          The server automatically prepends extra_args to every call (default:
+          #{DEFAULT_EXTRA_ARGS.join(' ')}).
+          Do NOT repeat these flags in your args array — they are already injected.
+          If you explicitly need to override one (e.g. --interactive=yes), include it
+          in your args; your value will take precedence because it appears after the
+          injected ones.
+          If credentials are missing or incomplete, the command will return an error;
+          report it and stop, never wait for input.
+
+        DISCOVERY — recommended sequence
+          Step 1 — enumerate all commands:
+            ["config", "commands"]
+            Returns { syntax, description } for every leaf command of every plugin.
+            Syntax notation: <arg> mandatory, [<arg>] optional, <a|b> enum, <arg...> variadic.
+            This single call covers all 800+ commands — no other discovery step is needed
+            unless you want details about a specific command or its Hash arguments.
+            IMPORTANT: never guess command names from training data. If you are unsure of
+            the exact subcommand name (e.g. shared_folders vs shared_inboxes), always call
+            ["config", "commands"] first to find the correct name.
+
+          Step 2 — inspect a Hash argument schema BEFORE calling any command with <data>:
+            MANDATORY: whenever the command syntax shows a <data> argument, you MUST call
+            "help" offline first. Never infer field names from server error messages.
+            ["<plugin>", "<cmd>", ..., "help"]
+            Replace the Hash positional argument with the literal string "help".
+            Returns a table of field names, types, and descriptions for that argument.
+            Example: ["aoc", "admin", "user", "create", "help"]
+            Note: only works for Hash-typed arguments, not for plain String arguments.
+
+          Step 2b — discover available query/filter parameters for list commands:
+            ["<plugin>", "<cmd>", ..., "--query=help"]
+            Add --query=help to any list command to see all supported filter parameters
+            with their types and descriptions.
+            Example: ["aoc", "admin", "user", "list", "--query=help"]
+            Example: ["faspex5", "admin", "packages", "list", "--query=help"]
+            Note: only works on commands that support --query filtering (list/delete).
+
+          Step 3 — list all options for a plugin as structured data:
+            ["config", "options", "<plugin>"]
+            Returns { option, description, allowed, deprecated } for every --flag
+            accepted by that plugin (global + plugin-specific, ~80 entries).
+            Use when you need to know the exact allowed values or find a specific flag.
+
+          Full documentation:
+            ["config", "documentation", "toc"]
+            Returns the table of contents: { level, title, anchor } for every heading.
+            ["config", "documentation", "local", "<anchor>"]
+            Returns only the section matching that anchor (same slugs as GitHub).
+            ["config", "documentation", "local", "--ui=text"]
+            Returns the complete README (~300 KB). Use only when a specific section
+            is insufficient and you need broader narrative context.
+
+        RESULT FORMAT
+          Structured data is always in structuredContent (a JSON object).
+          For list results, text content is limited to #{DEFAULT_MAX_TEXT_BYTES} bytes (whole items only).
+          When truncated, a WARNING block is appended: "WARNING: result truncated to N of TOTAL items."
+          You MUST read structuredContent.items to obtain the full dataset — never report
+          counts, totals, or search results from a truncated text block.
+
+        FILE LIST FOR TRANSFERS
+          For all transfers (upload, download, package send, …), append source file paths
+          at the end of the args array — no --sources flag needed.
+          ["server", "upload", "--to-folder=/dst", "/local/file1", "/local/file2"]
+          ["aoc", "packages", "send", "@:", "name=pkg", "recipients.0=user@example.com", "END",
+           "/local/file1", "/local/file2"]
+
+        EXAMPLES
+          ["config", "commands"]                       ← Step 1: full capability map
+          ["aoc", "admin", "user", "create", "help"]   ← Step 2: schema of <data> Hash
+          ["config", "options", "aoc"]                 ← Step 3: all --flags for aoc plugin
+          ["config", "documentation", "toc"]           ← TOC of local README
+          ["config", "documentation", "local",
+           "leveraging-ai-assistance"]                 ← single README section by anchor
+          ["aoc", "admin", "user", "create",
+           '@json:{"email":"a@b.com","name":"Alice"}',
+           "--url=https://org.ibmaspera.com", "--username=admin@org.com",
+           "--password=secret"]
+          ["server", "browse", "/",
+           "--url=https://host", "--username=user", "--password=secret"]
+          ["server", "upload", "--url=https://host", "--username=user", "--password=secret",
+           "--to-folder=/uploads", "/local/file1.txt", "/local/file2.txt"]
+          ["aoc", "packages", "list", "--workspace=MyWorkspace"]
+          ["node", "info", "--url=https://node-host",
+           "--username=user", "--password=pass"]
+      DESC
+
+      input_schema(
+        properties: {
+          args: {
+            type:        'array',
+            items:       {type: 'string'},
+            minItems:    1,
+            description: 'ascli arguments: first element is the plugin name, followed by action and --option=value flags'
+          }
+        },
+        required: ['args']
+      )
+
+      class << self
+        attr_accessor :max_text_bytes, :extra_args
+
+        def call(args:, server_context: nil)
+          effective_args = Array(extra_args || DEFAULT_EXTRA_ARGS) + args
+          Log.dump(:mcp_execute, effective_args)
+          runner = Runner.new(effective_args)
+          result = runner.run_with_result
+          case result
+          when Result::Nothing, Result::Empty, NilClass
+            MCP::Tool::Response.new([{type: 'text', text: ''}])
+          when Result::SingleObject, Result::ObjectList, Result::ValueList
+            # Apply --select filter in place (affects both text and structuredContent).
+            runner.context.formatter.filter_columns_on_select(result.data) if result.data.is_a?(Array)
+            # MCP spec requires structuredContent to be a JSON object (not an array).
+            structured = result.data.is_a?(Array) ? {items: result.data} : result.data
+            content = if result.data.is_a?(Array)
+              text_limit = max_text_bytes || DEFAULT_MAX_TEXT_BYTES
+              truncated_items = truncate_items_by_bytes(result.data, text_limit)
+              total = result.data.size
+              if truncated_items.size < total
+                [
+                  {type: 'text', text: JSON.generate(truncated_items)},
+                  {type: 'text', text: "WARNING: result truncated to #{truncated_items.size} of #{total} items. Full dataset available in structuredContent."}
+                ]
+              else
+                [{type: 'text', text: JSON.generate(result.data)}]
+              end
+            else
+              [{type: 'text', text: JSON.generate(result.data)}]
+            end
+            MCP::Tool::Response.new(content, structured_content: structured)
+          else
+            MCP::Tool::Response.new([{type: 'text', text: result.data.to_s}])
+          end
+        rescue Cli::SchemaRequest => e
+          schema_path = e.path
+          if schema_path.nil?
+            MCP::Tool::Response.new([{type: 'text', text: "#{e.class}: #{e.message} (no schema available)"}], error: true)
+          else
+            rows = schema_to_rows(Schema::Registry.instance.reader(schema_path))
+            structured = {items: rows}
+            MCP::Tool::Response.new([{type: 'text', text: JSON.generate(rows)}], structured_content: structured)
+          end
+        rescue SystemExit => e
+          MCP::Tool::Response.new([{type: 'text', text: "exited with status #{e.status}"}], error: !e.status.zero?)
+        rescue => e
+          MCP::Tool::Response.new([{type: 'text', text: "#{e.class}: #{dedupe_lines(e.message)}"}], error: true)
+        end
+
+        # Delegate to Schema::Reader#to_rows — semantic fields, no ANSI, MCP/JSON-ready.
+        def schema_to_rows(reader)
+          reader.to_rows
+        end
+
+        # Collapse consecutive duplicate lines in a multi-line message.
+        # Each run of identical lines is replaced by one line + "(×N)" suffix when N > 1.
+        def dedupe_lines(msg)
+          return msg unless msg.include?("\n")
+          msg.split("\n").chunk_while { |a, b| a == b }.map do |group|
+            group.size > 1 ? "#{group.first} (x#{group.size})" : group.first
+          end.join("\n")
+        end
+
+        # Returns the largest prefix of +items+ whose JSON serialization fits within +max_bytes+.
+        # Items are appended whole — no item is ever split mid-JSON.
+        def truncate_items_by_bytes(items, max_bytes)
+          buf = +''
+          items.each_with_index do |item, i|
+            fragment = (i.zero? ? '[' : ',') + JSON.generate(item)
+            break if buf.bytesize + fragment.bytesize + 1 > max_bytes # +1 for closing ']'
+            buf << fragment
+          end
+          buf.empty? ? [] : JSON.parse("#{buf}]")
+        end
+      end
+    end
+  end
+end

data/lib/aspera/cli/option_declarator.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'aspera/cli/parser'
+require 'aspera/cli/command_spec'
+
+module Aspera
+  module Cli
+    # Mixin providing declarative CLI option definitions (`option :name, ...`)
+    # and batch declaration onto a Parser instance (`declare_options(parser)`).
+    module OptionDeclarator
+      # Registry of OptionSpec objects defined on this class/module.
+      # @return [Hash{Symbol => OptionSpec}]
+      def option_specs
+        @option_specs ||= {}
+      end
+
+      # Declare an option in this class's registry.
+      #
+      # @param name        [Symbol]          Option name
+      # @param description [String, nil]     User-facing description
+      # @param short       [String, nil]     Single-character short form
+      # @param allowed     [Object, nil]     Allowed values
+      # @param default     [Object, nil]     Default value
+      # @param handler     [Symbol, Hash, nil] Handler (Symbol or Hash)
+      # @param deprecation [String, nil]     Deprecation message
+      # @param schema      [String, nil]     Schema reference
+      def option(name, description: nil,
+        short: nil, allowed: nil, default: nil,
+        handler: nil, deprecation: nil, schema: nil)
+        raise ArgumentError, "Duplicate option: #{name.inspect}" if option_specs.key?(name)
+        option_specs[name] = OptionSpec.new(
+          name:        name,
+          description: description,
+          short:       short,
+          allowed:     allowed,
+          default:     default,
+          handler:     handler,
+          deprecation: deprecation,
+          schema:      schema
+        )
+      end
+
+      # Declare all options registered on this class onto a Parser instance.
+      # Skips options already declared on the parser.
+      #
+      # @param parser [Aspera::Cli::Parser]
+      # @param target [Object, nil] default target object for Symbol handlers (defaults to self)
+      # @return [void]
+      def declare_options(parser, target: self)
+        option_specs.each_value do |spec|
+          next if parser.option_declared?(spec.name)
+          resolved_handler =
+            case spec.handler
+            when Symbol then {o: target, m: spec.handler}
+            when Hash   then spec.handler
+            end
+          parser.declare(
+            spec.name,
+            description: spec.description,
+            short:       spec.short,
+            allowed:     spec.allowed,
+            default:     spec.default,
+            handler:     resolved_handler,
+            deprecation: spec.deprecation,
+            schema:      schema_for_spec(spec)
+          )
+        end
+      end
+
+      private
+
+      def schema_for_spec(spec)
+        spec.schema
+      end
+    end
+  end
+end