mixin_bot 1.4.0 → 2.0.0

data/lib/mixin_bot/cli/node.rb

@@ -34,7 +34,7 @@ module MixinBot
           '-c',
           c.to_s
         )
-        distributions = eval o
+        distributions = parse_mixin_cli_output(o)
         spinner.update_title "#{distributions.size} mint distributions listed"
       end
 
@@ -54,7 +54,7 @@ module MixinBot
           '-x',
           tx
         )
-        tx = eval o
+        tx = parse_mixin_cli_output(o)
         spinner.update_title "#{tx[:outputs].size} transaction outputs found"
       end
 
@@ -92,6 +92,13 @@ module MixinBot
       $CHILD_STATUS.success?
     end
 
+    def parse_mixin_cli_output(output)
+      JSON.parse(output, symbolize_names: true)
+    rescue JSON::ParserError
+      # Mixin node CLI historically prints Ruby hash literals.
+      eval(output)
+    end
+
     def log(obj)
       if options[:pretty]
         if obj.is_a? String

data/lib/mixin_bot/cli/output.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+
+module MixinBot
+  ##
+  # Structured and human-friendly stdout/stderr formatting for mixinbot.
+  #
+  module CLIOutput
+    OUTPUT_FORMATS = %w[pretty json yaml].freeze
+
+    def cli_options
+      merged = options.dup
+      merged = parent_options.merge(merged) if respond_to?(:parent_options) && parent_options.present?
+      merged
+    end
+
+    def output_format
+      opts = cli_options
+      explicit = opts[:output].to_s.downcase if opts[:output].present?
+      return explicit if OUTPUT_FORMATS.include?(explicit)
+
+      return 'json' if opts.key?(:pretty) && opts[:pretty] == false
+
+      $stdout.tty? ? 'pretty' : 'json'
+    end
+
+    def structured_output?
+      %w[json yaml].include?(output_format)
+    end
+
+    def current_command_name
+      @current_command_name || self.class.name.split('::').last.sub(/CLI\z/, '').downcase
+    end
+
+    def with_command_name(name)
+      previous = @current_command_name
+      @current_command_name = name
+      yield
+    ensure
+      @current_command_name = previous
+    end
+
+    def emit_success(data, command: nil)
+      command_name = command || current_command_name
+      if structured_output?
+        write_stdout(encode_output(envelope('ok', command_name, data)))
+      else
+        write_pretty(data)
+      end
+    end
+
+    def emit_list(items:, total:, limit:, offset:, command: 'list')
+      payload = {
+        'items' => items,
+        'total' => total,
+        'limit' => limit,
+        'offset' => offset
+      }
+      emit_success(payload, command:)
+    end
+
+    def emit_info(message)
+      return if message.blank?
+
+      if structured_output?
+        warn(message)
+      else
+        warn(format_info(message))
+      end
+    end
+
+    def abort_with_error(message, kind: nil, hint: nil, exception: nil)
+      resolved_kind = kind || (exception && CLIErrors.kind_for_exception(exception)) || CLIErrors.kind_for_message(message)
+      hint ||= default_error_hint
+
+      if structured_output?
+        error_body = {
+          'status' => 'error',
+          'error' => {
+            'kind' => resolved_kind.to_s,
+            'message' => message.to_s
+          }
+        }
+        error_body['error']['hint'] = hint if hint.present?
+        warn(JSON.generate(error_body))
+      else
+        warn(format_error(message))
+      end
+      exit(1)
+    end
+
+    def print_result(obj, data_only: false, command: nil)
+      out =
+        case obj
+        when MixinBot::Models::ApiEnvelope
+          data_only ? (obj['data'] || obj.to_h) : obj.to_h
+        when Hash
+          data_only ? (obj['data'] || obj) : obj
+        else
+          obj
+        end
+
+      emit_success(out, command:)
+    end
+
+    def log(obj)
+      emit_success(obj)
+    end
+
+    def paginate_items(items, limit:, offset:)
+      limit = limit.to_i
+      offset = offset.to_i
+      limit = 100 if limit <= 0
+      offset = 0 if offset.negative?
+
+      total = items.size
+      slice = items.drop(offset).first(limit)
+      [slice, total, limit, offset]
+    end
+
+    def select_fields(items, fields)
+      return items if fields.blank?
+
+      keys = fields.split(',').map(&:strip).reject(&:empty?)
+      return items if keys.empty?
+
+      items.map do |item|
+        item.slice(*keys)
+      end
+    end
+
+    private
+
+    def envelope(status, command, data)
+      {
+        'status' => status,
+        'command' => command,
+        'data' => normalize_data(data)
+      }
+    end
+
+    def normalize_data(data)
+      case data
+      when MixinBot::Models::ApiEnvelope
+        data.to_h
+      when Hash
+        data.transform_keys(&:to_s)
+      else
+        data
+      end
+    end
+
+    def encode_output(payload)
+      case output_format
+      when 'yaml'
+        payload.to_yaml
+      else
+        JSON.generate(payload)
+      end
+    end
+
+    def write_stdout(text)
+      puts text
+    end
+
+    def write_pretty(obj)
+      if obj.is_a?(String)
+        puts obj
+      else
+        ap obj
+      end
+    end
+
+    def format_info(message)
+      if defined?(UI) && UI.respond_to?(:fmt)
+        UI.fmt(message.to_s)
+      else
+        message.to_s
+      end
+    end
+
+    def format_error(message)
+      if defined?(UI) && UI.respond_to?(:fmt)
+        UI.fmt("{{x}} #{message}")
+      else
+        "Error: #{message}"
+      end
+    end
+
+    def default_error_hint
+      'Run `mixinbot help` or `mixinbot schema -o json` for usage'
+    end
+  end
+end

data/lib/mixin_bot/cli/schema.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+module MixinBot
+  ##
+  # Builds clispec-shaped schema documents for mixinbot.
+  #
+  module CLISchema
+    MUTATING_COMMANDS = %w[
+      transfer legacy-transfer safetransfer authcode updatetip saferegister pay
+    ].freeze
+
+    MUTATING_API_METHOD_PREFIXES = %w[
+      create_ update_ delete_ send_ post_ authorize_ safe_register migrate_
+      build_inscribe transfer_app upload_
+    ].freeze
+
+    COMMAND_DEFINITIONS = [
+      {
+        'name' => 'version',
+        'description' => 'Display MixinBot gem version',
+        'mutating' => false,
+        'args' => [],
+        'output_fields' => [
+          { 'name' => 'version', 'type' => 'string' }
+        ]
+      },
+      {
+        'name' => 'schema',
+        'description' => 'Emit machine-readable CLI schema (clispec-shaped)',
+        'mutating' => false,
+        'args' => [
+          { 'name' => '--output', 'type' => 'string', 'required' => false,
+            'enum' => %w[pretty json yaml], 'default' => nil }
+        ],
+        'output_fields' => [
+          { 'name' => 'name', 'type' => 'string' },
+          { 'name' => 'version', 'type' => 'string' },
+          { 'name' => 'commands', 'type' => 'array' },
+          { 'name' => 'errors', 'type' => 'array' }
+        ]
+      },
+      {
+        'name' => 'list',
+        'description' => 'List callable MixinBot::API methods',
+        'mutating' => false,
+        'args' => [
+          { 'name' => 'FILTER', 'type' => 'string', 'required' => false },
+          { 'name' => '--limit', 'type' => 'integer', 'required' => false, 'default' => 100 },
+          { 'name' => '--offset', 'type' => 'integer', 'required' => false, 'default' => 0 },
+          { 'name' => '--fields', 'type' => 'string', 'required' => false,
+            'description' => 'Comma-separated fields: name,owner' }
+        ],
+        'output_fields' => [
+          { 'name' => 'items', 'type' => 'array' },
+          { 'name' => 'total', 'type' => 'integer' },
+          { 'name' => 'limit', 'type' => 'integer' },
+          { 'name' => 'offset', 'type' => 'integer' }
+        ]
+      },
+      {
+        'name' => 'call',
+        'description' => 'Invoke a MixinBot::API method with JSON keyword arguments',
+        'mutating' => 'conditional',
+        'mutating_note' => 'Mutating when METHOD matches write operations; use `mixinbot list` to inspect',
+        'args' => [
+          { 'name' => 'METHOD', 'type' => 'string', 'required' => true },
+          { 'name' => '--keystore', 'type' => 'string', 'required' => false, 'aliases' => ['-k'] },
+          { 'name' => '--data', 'type' => 'string', 'required' => false, 'default' => '{}', 'aliases' => ['-d'] },
+          { 'name' => '--data-only', 'type' => 'boolean', 'required' => false, 'default' => false }
+        ],
+        'output_fields' => [
+          { 'name' => 'data', 'type' => 'object | array | string' }
+        ]
+      },
+      {
+        'name' => 'api',
+        'description' => 'Signed GET/POST request to a Mixin API path',
+        'mutating' => 'conditional',
+        'mutating_note' => 'Mutating when --method POST',
+        'args' => [
+          { 'name' => 'PATH', 'type' => 'string', 'required' => true },
+          { 'name' => '--keystore', 'type' => 'string', 'required' => true, 'aliases' => ['-k'] },
+          { 'name' => '--method', 'type' => 'string', 'required' => false, 'default' => 'GET', 'aliases' => ['-m'] },
+          { 'name' => '--data', 'type' => 'string', 'required' => false, 'default' => '{}', 'aliases' => ['-d'] },
+          { 'name' => '--data-only', 'type' => 'boolean', 'required' => false, 'default' => true }
+        ]
+      },
+      {
+        'name' => 'transfer',
+        'description' => 'Safe transfer to USER_ID',
+        'mutating' => true,
+        'args' => [
+          { 'name' => 'USER_ID', 'type' => 'string', 'required' => true },
+          { 'name' => '--keystore', 'type' => 'string', 'required' => true, 'aliases' => ['-k'] },
+          { 'name' => '--asset', 'type' => 'string', 'required' => true },
+          { 'name' => '--amount', 'type' => 'string', 'required' => true },
+          { 'name' => '--memo', 'type' => 'string', 'required' => false },
+          { 'name' => '--trace', 'type' => 'string', 'required' => false },
+          { 'name' => '--spend-key', 'type' => 'string', 'required' => false },
+          { 'name' => '--dry-run', 'type' => 'boolean', 'required' => false, 'default' => false }
+        ]
+      },
+      {
+        'name' => 'legacy-transfer',
+        'description' => 'Legacy POST /transfers (deprecated)',
+        'mutating' => true,
+        'args' => [
+          { 'name' => 'USER_ID', 'type' => 'string', 'required' => true },
+          { 'name' => '--keystore', 'type' => 'string', 'required' => true, 'aliases' => ['-k'] },
+          { 'name' => '--asset', 'type' => 'string', 'required' => true },
+          { 'name' => '--amount', 'type' => 'number', 'required' => true }
+        ]
+      },
+      {
+        'name' => 'safetransfer',
+        'description' => 'Alias for transfer (deprecated)',
+        'mutating' => true,
+        'args' => []
+      },
+      {
+        'name' => 'authcode',
+        'description' => 'OAuth authorization code',
+        'mutating' => true,
+        'args' => [
+          { 'name' => '--keystore', 'type' => 'string', 'required' => true, 'aliases' => ['-k'] },
+          { 'name' => '--app-id', 'type' => 'string', 'required' => true, 'aliases' => ['-c'] }
+        ]
+      },
+      {
+        'name' => 'saferegister',
+        'description' => 'Register on SAFE network',
+        'mutating' => true,
+        'args' => [
+          { 'name' => '--keystore', 'type' => 'string', 'required' => true, 'aliases' => ['-k'] },
+          { 'name' => '--spend-key', 'type' => 'string', 'required' => true }
+        ]
+      },
+      {
+        'name' => 'pay',
+        'description' => 'Generate Safe payment URL',
+        'mutating' => false,
+        'args' => [
+          { 'name' => '--members', 'type' => 'array', 'required' => true },
+          { 'name' => '--asset', 'type' => 'string', 'required' => true },
+          { 'name' => '--amount', 'type' => 'string', 'required' => true }
+        ]
+      },
+      {
+        'name' => 'encrypt',
+        'description' => 'Encrypt PIN using session keys',
+        'mutating' => false,
+        'args' => [
+          { 'name' => 'PIN', 'type' => 'string', 'required' => true },
+          { 'name' => '--keystore', 'type' => 'string', 'required' => true, 'aliases' => ['-k'] }
+        ]
+      },
+      {
+        'name' => 'verifypin',
+        'description' => 'Verify PIN',
+        'mutating' => false,
+        'args' => [
+          { 'name' => 'PIN', 'type' => 'string', 'required' => true },
+          { 'name' => '--keystore', 'type' => 'string', 'required' => true, 'aliases' => ['-k'] }
+        ]
+      },
+      {
+        'name' => 'updatetip',
+        'description' => 'Update TIP PIN',
+        'mutating' => true,
+        'args' => [
+          { 'name' => 'PIN', 'type' => 'string', 'required' => true },
+          { 'name' => '--keystore', 'type' => 'string', 'required' => true, 'aliases' => ['-k'] }
+        ]
+      },
+      {
+        'name' => 'utils',
+        'description' => 'Utils subcommands (call, list)',
+        'mutating' => false,
+        'args' => []
+      },
+      {
+        'name' => 'utils call',
+        'description' => 'Invoke a MixinBot.utils method',
+        'mutating' => false,
+        'args' => [
+          { 'name' => 'METHOD', 'type' => 'string', 'required' => true },
+          { 'name' => '--data', 'type' => 'string', 'required' => false, 'default' => '{}', 'aliases' => ['-d'] }
+        ]
+      },
+      {
+        'name' => 'utils list',
+        'description' => 'List callable MixinBot.utils methods',
+        'mutating' => false,
+        'args' => [
+          { 'name' => 'FILTER', 'type' => 'string', 'required' => false },
+          { 'name' => '--limit', 'type' => 'integer', 'required' => false, 'default' => 100 },
+          { 'name' => '--offset', 'type' => 'integer', 'required' => false, 'default' => 0 },
+          { 'name' => '--fields', 'type' => 'string', 'required' => false, 'default' => 'name' }
+        ]
+      },
+      {
+        'name' => 'unique',
+        'description' => 'Deterministic UUID from two or more UUIDs',
+        'mutating' => false,
+        'args' => [{ 'name' => 'UUIDS', 'type' => 'array', 'required' => true }]
+      },
+      {
+        'name' => 'generatetrace',
+        'description' => 'Trace UUID from transaction hash',
+        'mutating' => false,
+        'args' => [{ 'name' => 'HASH', 'type' => 'string', 'required' => true }]
+      },
+      {
+        'name' => 'decodetx',
+        'description' => 'Decode raw transaction hex',
+        'mutating' => false,
+        'args' => [{ 'name' => 'TRANSACTION', 'type' => 'string', 'required' => true }]
+      },
+      {
+        'name' => 'nftmemo',
+        'description' => 'NFT mint memo',
+        'mutating' => false,
+        'args' => []
+      },
+      {
+        'name' => 'rsa',
+        'description' => 'Generate RSA key pair',
+        'mutating' => false,
+        'args' => []
+      },
+      {
+        'name' => 'ed25519',
+        'description' => 'Generate Ed25519 key pair',
+        'mutating' => false,
+        'args' => []
+      }
+    ].freeze
+
+    module_function
+
+    def build
+      {
+        'name' => 'mixinbot',
+        'version' => MixinBot::VERSION,
+        'license' => 'MIT',
+        'commands' => commands_with_globals,
+        'errors' => CLIErrors.schema_errors,
+        'api_method_count' => CLIHelpers.api_callable_methods.size,
+        'api_method_registry' => 'mixinbot list -o json'
+      }
+    end
+
+    def commands_with_globals
+      global_args = [
+        { 'name' => '--apihost', 'type' => 'string', 'required' => false, 'default' => 'api.mixin.one',
+          'aliases' => ['-a'] },
+        { 'name' => '--output', 'type' => 'string', 'required' => false,
+          'enum' => CLIOutput::OUTPUT_FORMATS, 'aliases' => ['-o'],
+          'description' => 'Output format; defaults to pretty in TTY, json when piped' },
+        { 'name' => '--pretty', 'type' => 'boolean', 'required' => false, 'default' => true,
+          'aliases' => ['-r'], 'description' => 'Alias for --output pretty' }
+      ]
+
+      COMMAND_DEFINITIONS.map do |cmd|
+        cmd.merge('global_args' => global_args)
+      end
+    end
+
+    def mutating_api_method?(method_name)
+      name = method_name.to_s
+      MUTATING_API_METHOD_PREFIXES.any? { |prefix| name.start_with?(prefix) }
+    end
+  end
+end

data/lib/mixin_bot/cli/schema_command.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module MixinBot
+  class CLI
+    desc 'schema', 'Emit machine-readable CLI schema (clispec-shaped)'
+    long_desc <<-LONGDESC
+      Discover mixinbot commands, arguments, and error kinds without parsing --help.
+
+      Examples:
+
+        $ mixinbot schema -o json
+        $ mixinbot schema -o json | jq '.commands[].name'
+        $ mixinbot schema -o yaml
+    LONGDESC
+    def schema
+      with_command_name('schema') do
+        emit_success(CLISchema.build, command: 'schema')
+      end
+    end
+  end
+end

data/lib/mixin_bot/cli/utils.rb

@@ -1,45 +1,141 @@
 # frozen_string_literal: true
 
 module MixinBot
-  class CLI < Thor
-    desc 'encrypt PIN', 'encrypt PIN using private key'
+  class UtilsCLI < Thor
+    include CLIOutput
+    include CLIHelpers
+
+    desc 'call METHOD', 'Invoke a MixinBot.utils method'
+    option :data, type: :string, aliases: '-d', default: '{}', desc: 'JSON object of keyword arguments'
+    def call(method_name, *positional)
+      with_command_name('utils call') do
+        kwargs = parse_utils_json_data(options[:data])
+        result = invoke_utils_method(method_name, kwargs:, positional:)
+        emit_success(result, command: 'utils call')
+      end
+    end
+
+    desc 'list [FILTER]', 'List callable MixinBot.utils methods'
+    option :limit, type: :numeric, default: 100, desc: 'Maximum items to return'
+    option :offset, type: :numeric, default: 0, desc: 'Number of items to skip'
+    option :fields, type: :string, default: 'name', desc: 'Comma-separated fields for JSON output'
+    def list(filter = nil)
+      with_command_name('utils list') do
+        methods = CLIHelpers.utils_callable_methods
+        if filter.present?
+          needle = filter.downcase
+          methods = methods.select { |m| m.to_s.downcase.include?(needle) }
+        end
+
+        items = methods.map { |name| { 'name' => name.to_s } }
+        page, total, limit, offset = paginate_items(items, limit: options[:limit], offset: options[:offset])
+        page = select_fields(page, options[:fields])
+
+        if structured_output?
+          emit_list(items: page, total:, limit:, offset:, command: 'utils list')
+        else
+          page.each { |item| puts item['name'] }
+          emit_info("Showing #{page.size} of #{total} (limit=#{limit}, offset=#{offset})") if total > limit || offset.positive?
+        end
+      end
+    end
+
+    private
+
+    def parse_utils_json_data(json_string, label: 'data')
+      return {} if json_string.blank?
+
+      parsed = JSON.parse(json_string)
+      abort_with_error("#{label} must be a JSON object", kind: :invalid_args) unless parsed.is_a?(Hash)
+
+      parsed.transform_keys(&:to_sym)
+    rescue JSON::ParserError => e
+      abort_with_error("invalid JSON for #{label}: #{e.message}", kind: :invalid_args)
+    end
+
+    def invoke_utils_method(method_name, kwargs: {}, positional: [])
+      sym = method_name.to_sym
+      unless CLIHelpers.utils_callable_methods.include?(sym)
+        abort_with_error(
+          format('unknown utils method: %<method>s', method: method_name),
+          kind: :unsupported,
+          hint: 'mixinbot utils list'
+        )
+      end
+
+      MixinBot.utils.public_send(sym, *positional, **kwargs)
+    rescue ::ArgumentError => e
+      abort_with_error(
+        format('invalid arguments for utils.%<method>s: %<error>s', method: method_name, error: e.message),
+        kind: :invalid_args
+      )
+    end
+  end
+
+  class CLI
+    desc 'utils', 'Utils dispatcher (call, list)'
+    subcommand 'utils', UtilsCLI
+
+    desc 'encrypt PIN', 'Encrypt PIN using session keys'
     option :keystore, type: :string, aliases: '-k', required: true, desc: 'keystore or keystore.json file path'
     option :iterator, type: :string, aliases: '-i', desc: 'Iterator'
     def encrypt(pin)
-      log api_instance.encrypt_pin pin.to_s, iterator: options[:iterator]
+      with_command_name('encrypt') do
+        setup_api_instance!
+        emit_success(api_instance.encrypt_pin(pin.to_s, iterator: options[:iterator]), command: 'encrypt')
+      end
     end
 
-    desc 'unique UUIDS', 'generate unique UUID for two or more UUIDs'
+    desc 'unique UUIDS', 'Deterministic UUID from two or more UUIDs'
     def unique(*uuids)
-      log MixinBot.utils.unique_uuid(*uuids)
+      with_command_name('unique') do
+        emit_success(MixinBot.utils.unique_uuid(*uuids), command: 'unique')
+      end
     end
 
-    desc 'generatetrace HASH', 'generate trace ID from Tx hash'
+    desc 'generatetrace HASH', 'Trace UUID from transaction hash'
+    option :index, type: :numeric, default: 0, desc: 'Output index'
     def generatetrace(hash)
-      log MixinBot.utils.generate_trace_from_hash(hash)
+      with_command_name('generatetrace') do
+        emit_success(
+          MixinBot.utils.generate_trace_from_hash(hash, options[:index]),
+          command: 'generatetrace'
+        )
+      end
     end
 
-    desc 'decodetx TRANSACTION', 'decode raw transaction'
+    desc 'decodetx TRANSACTION', 'Decode raw transaction hex'
     def decodetx(transaction)
-      log MixinBot.utils.decode_raw_transaction(transaction)
+      with_command_name('decodetx') do
+        emit_success(MixinBot.utils.decode_raw_transaction(transaction), command: 'decodetx')
+      end
     end
 
-    desc 'nftmemo', 'memo for mint NFT'
-    option :collection, type: :string, required: true, aliases: '-c', desc: 'Collection ID, UUID'
-    option :token, type: :numeric, required: true, aliases: '-t', desc: 'Token ID, Integer'
-    option :hash, type: :string, required: true, aliases: '-h', desc: 'Hash of NFT metadata, 256-bit string'
+    desc 'nftmemo', 'NFT mint memo'
+    option :collection, type: :string, required: true, aliases: '-c', desc: 'Collection ID (UUID)'
+    option :token, type: :numeric, required: true, aliases: '-t', desc: 'Token ID'
+    option :hash, type: :string, required: true, aliases: '-h', desc: 'Metadata hash (256-bit hex)'
     def nftmemo
-      log MixinBot.utils.nft(options[:collection], options[:token], options[:hash])
+      with_command_name('nftmemo') do
+        emit_success(
+          MixinBot.utils.nft_memo(options[:collection], options[:token], options[:hash]),
+          command: 'nftmemo'
+        )
+      end
     end
 
-    desc 'rsa', 'generate RSA key'
+    desc 'rsa', 'Generate RSA key pair'
     def rsa
-      log MixinBot.utils.generate_rsa_key
+      with_command_name('rsa') do
+        emit_success(MixinBot.utils.generate_rsa_key, command: 'rsa')
+      end
     end
 
-    desc 'ed25519', 'generate Ed25519 key'
+    desc 'ed25519', 'Generate Ed25519 key pair'
     def ed25519
-      log MixinBot.utils.generate_ed25519_key
+      with_command_name('ed25519') do
+        emit_success(MixinBot.utils.generate_ed25519_key, command: 'ed25519')
+      end
     end
   end
 end