aspera-cli 4.26.2 → 4.27.0

data/lib/aspera/cli/http.rb

@@ -4,6 +4,10 @@ require 'aspera/cli/special_values'
 require 'aspera/log'
 require 'aspera/assert'
 require 'aspera/line_logger'
+require 'aspera/schema/registry'
+require 'aspera/rest'
+require 'aspera/oauth'
+require 'aspera/ssl'
 require 'openssl'
 
 module Aspera
@@ -29,19 +33,64 @@ 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
+
+      class << self
+        # Declare all HTTP/S CLI options (metadata only - no handler binding yet).
+        # Called once from Config#initialize before this instance is available as a target.
+        # Handlers are bound in a second pass via bind_options once the instance exists.
+        # @param options [Aspera::Cli::Parser] CLI options manager to declare options into
+        # @return [nil]
+        def declare_options(options)
+          options.declare(:insecure,           description: 'HTTP/S: Do not validate any certificate',                   allowed: Allowed::TYPES_BOOLEAN, default: false)
+          options.declare(:ignore_certificate, description: 'HTTP/S: Do not validate certificate for these URLs',        allowed: [Array, NilClass])
+          options.declare(:warn_insecure,      description: 'HTTP/S: Issue a warning if certificate is ignored',         allowed: Allowed::TYPES_BOOLEAN, default: true)
+          options.declare(:cert_stores,        description: 'HTTP/S: List of folder with trusted certificates',          allowed: Allowed::TYPES_STRING_ARRAY)
+          options.declare(:http_options,       schema: Schema::Registry::HTTP_OPTIONS)
+          options.declare(:http_proxy,         description: 'HTTP/S: URL for proxy with optional credentials')
+          nil
+        end
+      end
+
+      # 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 +113,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
@@ -90,7 +139,8 @@ 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'}
         if @certificate_store.nil?
@@ -126,6 +176,7 @@ module Aspera
           end
         end
         @certificate_paths.uniq!
+        nil
       end
 
       # Return cert file paths (computes OS defaults lazily if never set).
@@ -145,12 +196,11 @@ 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?
         @http_options.each do |k, v|
@@ -161,6 +211,7 @@ module Aspera
             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.log.debug{"smtp=#{smtp}"}
+        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,198 @@
+# frozen_string_literal: true
+
+# cspell:ignore ascli
+
+require 'json'
+require 'aspera/log'
+require 'aspera/cli/runner'
+require 'aspera/cli/error'
+unless defined?(MCP::Tool)
+  begin
+    require 'mcp'
+  rescue LoadError
+    raise Cli::Error, "The 'mcp' gem is required. Install it with: gem install mcp"
+  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 (use for Hash/Array arguments)
+            "@preset:name"  — expand a saved credential preset
+            "@env:VAR"      — read value from environment variable
+            "@file:/path"   — read value from a file
+
+        AUTOMATIC FLAGS
+          The server automatically prepends extra_args to every call (default:
+          --interactive=no and --transfer.asynchronous=true).
+          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 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}: #{e.message}"}], error: true)
+        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