aspera-cli 4.27.2 → 4.27.3

data/lib/aspera/cli/mcp_tool.rb

@@ -4,6 +4,7 @@
 
 require 'json'
 require 'aspera/log'
+require 'aspera/secret_hider'
 require 'aspera/cli/runner'
 require 'aspera/cli/error'
 require 'aspera/schema/reader'
@@ -36,100 +37,61 @@ module Aspera
         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
+          Elements 1+: sub-commands, positional arguments, and --option=value flags in any order.
+          Structured values use an extended-value prefix on the relevant element:
+            "@json:{...}"   — inline JSON object or array (preferred: no shell quoting)
+            "@preset:name"  — expand a saved 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.
+          The server prepends extra_args to every call (default: #{DEFAULT_EXTRA_ARGS.join(' ')}).
+          Do NOT repeat them. To override one, include it in args: later values take precedence.
+          Commands never prompt: if credentials are missing, an error is returned; report it and stop.
+
+        DISCOVERY — never guess command or field names from training data
+          Step 1 — commands of a plugin, with syntax:
+            ["config", "commands", "<plugin>"]
+            Returns { syntax, description } for every command of that plugin.
+            Notation: <arg> mandatory, [<arg>] optional, <a|b> enum, <arg...> variadic, <arg:Hash> typed.
+            A line ending with <command...> and "(see: <plugin> <path>)" provides the commands of that path:
+            list them with ["config", "commands", "<plugin>", "<command>", ...] (command words only).
+            Omit <plugin> to list the commands of all plugins (large).
+          Step 2 — schema of a Hash argument (shown <name:Hash>), MANDATORY before calling such a command:
             ["<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:
+            Put the literal "help" in place of the Hash argument. Returns field names, types,
+            required flags and descriptions. Never infer fields from server error messages.
+          Step 2b — filter parameters of a list command:
             ["<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:
+          Step 3 — all --flags of a plugin, with allowed values:
             ["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.
+          Documentation:
+            ["config", "documentation", "toc"]              → { level, title, anchor } per heading
+            ["config", "documentation", "local", "<anchor>"] → one README section
+          Presets (saved credentials):
+            ["config", "preset", "overview"]
 
         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.
+          Structured data is always in structuredContent (a JSON object; lists are under "items").
+          For lists, text content is limited to #{DEFAULT_MAX_TEXT_BYTES} bytes (whole items only);
+          when truncated, a WARNING line gives the real total. Read structuredContent.items for
+          the full dataset — never report counts 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"]
+          For all transfers (upload, download, package send, …), append source paths at the
+          end of args — no --sources flag needed.
 
         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"]
+          ["config", "commands", "aoc"]
+          ["aoc", "admin", "user", "create", "help"]
+          ["config", "options", "aoc"]
+          ["config", "documentation", "local", "leveraging-ai-assistance"]
+          ["aoc", "--preset=myaoc", "packages", "list"]
+          ["aoc", "--preset=myaoc", "admin", "user", "create", '@json:{"email":"a@b.com","name":"Alice"}']
+          ["aoc", "--preset=myaoc", "packages", "send",
+           '@json:{"name":"pkg","recipients":["user@example.com"]}', "/local/a.txt", "/local/b.txt"]
+          ["server", "--preset=myserver", "upload", "--to-folder=/uploads", "/local/a.txt"]
+          ["server", "browse", "/", "--url=ssh://host:33001", "--username=user", "--password=secret"]
       DESC
 
       input_schema(
@@ -156,6 +118,8 @@ module Aspera
           when Result::Nothing, Result::Empty, NilClass
             MCP::Tool::Response.new([{type: 'text', text: ''}])
           when Result::SingleObject, Result::ObjectList, Result::ValueList
+            # Secrets never reach the AI client, whatever the output format requested in args.
+            SecretHider.instance.deep_remove_secret(result.data)
             # 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).
@@ -177,7 +141,7 @@ module Aspera
             end
             MCP::Tool::Response.new(content, structured_content: structured)
           else
-            MCP::Tool::Response.new([{type: 'text', text: result.data.to_s}])
+            MCP::Tool::Response.new([{type: 'text', text: SecretHider.instance.hide_secrets_in_string(result.data.to_s, all: true)}])
           end
         rescue Cli::SchemaRequest => e
           schema_path = e.path
@@ -208,7 +172,7 @@ module Aspera
           end.join("\n")
         end
 
-        # Returns the largest prefix of +items+ whose JSON serialization fits within +max_bytes+.
+        # 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 = +''

data/lib/aspera/cli/option_declarator.rb

@@ -16,62 +16,53 @@ module Aspera
 
       # 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
+      # @param name        [Symbol]                  Option name
+      # @param description [String, nil]             User-facing description; if nil, derived from schema: title/description
+      # @param short       [String, nil]             Single-character short form (without leading '-')
+      # @param allowed     [Object, nil]             Allowed values (see OptionValue)
+      # @param default     [Object, nil]             Default value
+      # @param on_set     [Symbol, Proc, #call, nil] `on_set` callback (see OptionSpec)
+      # @param shorthand   [String, nil]             For a `Hash` option: a `String` value is stored as `{shorthand => value}`
+      # @param deprecation [Hash, nil]               Deprecation `{last:, message:}` forwarded to options.declare (see `Deprecation`)
+      # @param schema      [String, nil]             Schema reference (e.g. "opts:components.schemas.Foo");
+      #                                              when description: is nil, the schema title or first description line is used
       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
+        on_set: nil, shorthand: nil, deprecation: nil, schema: nil)
+        register_option_spec(
+          OptionSpec.new(
+            name:        name,
+            description: description,
+            short:       short,
+            allowed:     allowed,
+            default:     default,
+            on_set:      on_set,
+            shorthand:   shorthand,
+            deprecation: deprecation,
+            schema:      schema
+          )
         )
       end
 
+      # Store an OptionSpec in this class's registry.
+      # @param spec [OptionSpec]
+      # @raise [ArgumentError] on duplicate option name
+      def register_option_spec(spec)
+        raise ArgumentError, "Duplicate option: #{spec.name.inspect}" if option_specs.key?(spec.name)
+        option_specs[spec.name] = spec
+      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)
+      # @param target [Object, nil] default target object for Symbol and Proc `on_set` callbacks (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)
-          )
+          spec.declare_on(parser, target: target) unless parser.option_declared?(spec.name)
         end
       end
-
-      private
-
-      def schema_for_spec(spec)
-        spec.schema
-      end
     end
   end
 end

data/lib/aspera/cli/option_registry.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'aspera/cli/option_value'
+require 'aspera/cli/error'
+require 'aspera/assert'
+
+module Aspera
+  module Cli
+    # Declared options, and their lookup by name: long, short, or unique abbreviation.
+    class OptionRegistry
+      # @return [Hash{Symbol => OptionValue}] declared options, in declaration order
+      attr_reader :options
+      # @return [String] help section of options declared next
+      attr_accessor :group
+
+      def initialize
+        @options = {}
+        # Short option char -> option, e.g. {'h' => help option}
+        @short_options = {}
+        @group = 'global'
+      end
+
+      # Register a new option
+      # @param option [OptionValue] option to register
+      # @param short  [String, nil] short option char
+      # @return [OptionValue] the option
+      def add(option, short: nil)
+        Aspera.assert(!@options.key?(option.option)) { "#{option.option} already declared" }
+        option.group = @group
+        option.short = short
+        @options[option.option] = option
+        @short_options[short] = option unless short.nil?
+        option
+      end
+
+      # @param option_symbol [Symbol] option name
+      # @return [Boolean] `true` if option is declared
+      def declared?(option_symbol) = @options.key?(option_symbol)
+
+      # @param option_symbol [Symbol] option name
+      # @return [OptionValue] declared option
+      # @raise [BadArgument] if option is not declared
+      def fetch(option_symbol)
+        Aspera.assert(@options.key?(option_symbol), type: BadArgument) { "Unknown option: #{option_symbol}" }
+        @options[option_symbol]
+      end
+
+      # @param char [String] short option char
+      # @return [OptionValue, nil] declared option, or `nil`
+      def by_short(char) = @short_options[char]
+
+      # Find long option by exact name, or by unique abbreviation.
+      # @param name              [String]  option name with underscores
+      # @param allow_abbreviation [Boolean] accept a unique prefix of a declared option
+      # @return [OptionValue, nil] declared option, or `nil` if none matches (yet)
+      # @raise [BadArgument] if abbreviation is ambiguous
+      def by_long(name, allow_abbreviation: true)
+        option = @options[name.to_sym]
+        return option if !option.nil? || !allow_abbreviation
+        candidates = @options.keys.select { |k| k.to_s.start_with?(name) }
+        return if candidates.empty?
+        Aspera.assert(candidates.length.eql?(1), type: BadArgument) do
+          Parser.multi_choice_assert_msg("Ambiguous option: #{Parser.option_name_to_line(name)}", candidates.map { |c| Parser.option_name_to_line(c) })
+        end
+        @options[candidates.first]
+      end
+    end
+  end
+end

data/lib/aspera/cli/option_types.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'aspera/cli/error'
+require 'aspera/assert'
+
+module Aspera
+  module Cli
+    # Exception raised when schema is asked (`help`)
+    class SchemaRequest < Error
+      # Value of option or argument that requests its schema
+      KEYWORD = 'help'
+
+      # @return [String, nil] path to schema file
+      attr_reader :path
+
+      # @param type [Symbol] :argument or :option
+      # @param name [String] name of the option/argument
+      # @param schema_path [String, nil] path to schema file, or `nil` if not available
+      def initialize(type, name, schema_path)
+        super("#{type}: #{name}")
+        @path = schema_path
+      end
+    end
+
+    # Values accepted for boolean options: `true`, `false`, `yes`, `no`
+    module BoolValue
+      # Symbol for `true`
+      YES_SYM = :yes
+      # Symbol for `false`
+      NO_SYM = :no
+      # Values meaning `false`
+      FALSE_VALUES = [NO_SYM, false].freeze
+      # Values meaning `true`
+      TRUE_VALUES = [YES_SYM, true].freeze
+      private_constant :FALSE_VALUES, :TRUE_VALUES
+      # Boolean values
+      # @return [Array<true, false, :yes, :no>]
+      ALL = (TRUE_VALUES + FALSE_VALUES).freeze
+      # `false` and `true`
+      TYPES = [FalseClass, TrueClass].freeze
+      # `:no` and `:yes`
+      SYMBOLS = [NO_SYM, YES_SYM].freeze
+      # @return [Boolean] `true` if value is a value for `true` in `ALL`
+      def true?(enum)
+        Aspera.assert_values(enum, ALL) { 'boolean' }
+        TRUE_VALUES.include?(enum)
+      end
+
+      # @return [Boolean] `true` if value is a value for `true` or `false` in ALL
+      def symbol?(sym)
+        ALL.include?(sym)
+      end
+      module_function :true?, :symbol?
+    end
+
+    # Type specifiers for the `allowed:` parameter of option declarations.
+    # Public API: STRING_ARRAY, SYMBOL_ARRAY, INTEGER, BOOLEAN, NONE.
+    # Internal (do not pass as `allowed:`):
+    #   ENUM   - derived internally when `allowed:` is an Array<Symbol> (enum list)
+    #   STRING - the implicit default; equivalent to omitting `allowed:` entirely
+    module Type
+      # Option value is a String or Array of Strings (cumulative)
+      STRING_ARRAY = [Array, String].freeze
+      # Option value is a Symbol from a constrained list; use as prefix: SYMBOL_ARRAY + [:val1, :val2]
+      SYMBOL_ARRAY = [Array, Symbol].freeze
+      # Option value is coerced to Integer
+      INTEGER = [Integer].freeze
+      # Option value is a Boolean
+      BOOLEAN = BoolValue::TYPES
+      # Option has no value — it is a flag switch (e.g. `-N`, `--help`)
+      NONE = [].freeze
+      # Internal: derived when allowed: is an Array<Symbol>; do not pass directly
+      ENUM   = [Symbol].freeze
+      # Internal: implicit default (String); equivalent to omitting allowed: entirely
+      STRING = [String].freeze
+    end
+
+    # Sources of option values.
+    # A value is ignored if the option was already set from a source with higher priority.
+    module OptionSource
+      # Source -> priority (higher wins)
+      PRIORITY = {
+        default:       0,
+        # Default preset for plugin (added with `override: false`)
+        plugin_preset: 1,
+        preset:        2,
+        env:           3,
+        cmdline:       4,
+        # Set by code, or asked to user: same as command line
+        code:          4,
+        interactive:   4
+      }.freeze
+
+      class << self
+        # @param source [Symbol] one of `PRIORITY` keys
+        # @return [Integer] priority of source
+        def priority(source)
+          PRIORITY.fetch(source) { Aspera.error_unexpected_value(source) { 'option source' } }
+        end
+      end
+    end
+  end
+end