opn_api 0.1.0

data/lib/opn_api/cli/formatter.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+
+module OpnApi
+  module CLI
+    # Output formatter for CLI results. Supports table, JSON, and YAML output.
+    #
+    # Table output supports field filtering:
+    # - Explicit fields via -F (e.g. -F uuid,name,type)
+    # - Default: first 5 fields (to keep output readable)
+    # - All fields via -A
+    # JSON and YAML always output all data unmodified.
+    module Formatter
+      # Default number of columns shown in table output when no -F or -A is given.
+      DEFAULT_MAX_FIELDS = 5
+
+      module_function
+
+      # Formats data according to the specified format.
+      #
+      # @param data [Object] Data to format (Hash, Array, String)
+      # @param format [Symbol] Output format (:table, :json, :yaml)
+      # @param fields [Array<String>, nil] Explicit field names for table output
+      # @param all_fields [Boolean] Show all fields in table output
+      # @param show_empty [Boolean] Show empty fields in table output (default: hidden)
+      # @return [String] Formatted output
+      def format(data, format: :table, fields: nil, all_fields: false, show_empty: false)
+        case format
+        when :json
+          format_json(data)
+        when :yaml
+          format_yaml(data)
+        else
+          format_table(data, fields: fields, all_fields: all_fields, show_empty: show_empty)
+        end
+      end
+
+      # Pretty-printed JSON output (always full data).
+      def format_json(data)
+        JSON.pretty_generate(data)
+      end
+
+      # YAML output (always full data).
+      def format_yaml(data)
+        data.to_yaml
+      end
+
+      # Human-readable table output with optional field filtering.
+      def format_table(data, fields: nil, all_fields: false, show_empty: false)
+        case data
+        when Array
+          format_array_table(data, fields: fields, all_fields: all_fields)
+        when Hash
+          format_hash_table(data, show_empty: show_empty)
+        else
+          data.to_s
+        end
+      end
+
+      # Formats an array of hashes as a column-aligned table.
+      # Applies field filtering for readability.
+      def format_array_table(rows, fields: nil, all_fields: false)
+        return '(no results)' if rows.empty?
+
+        # Flatten nested values to strings for display
+        flat_rows = rows.map do |row|
+          row.transform_values { |v| v.is_a?(Hash) || v.is_a?(Array) ? JSON.generate(v) : v.to_s }
+        end
+
+        # Determine which columns to show
+        all_keys = flat_rows.flat_map(&:keys).uniq
+        display_keys = select_display_keys(all_keys, fields: fields, all_fields: all_fields)
+
+        # Calculate column widths
+        widths = display_keys.to_h do |k|
+          [k, ([k.length] + flat_rows.map { |r| r.fetch(k, '').length }).max]
+        end
+
+        # Header line
+        header = display_keys.map { |k| k.ljust(widths[k]) }.join('  ')
+        separator = display_keys.map { |k| '-' * widths[k] }.join('  ')
+
+        # Data lines
+        lines = flat_rows.map do |row|
+          display_keys.map { |k| row.fetch(k, '').ljust(widths[k]) }.join('  ')
+        end
+
+        # Add hint about hidden fields if any were truncated
+        result = [header, separator, *lines].join("\n")
+        hidden_count = all_keys.length - display_keys.length
+        if hidden_count.positive?
+          result += "\n\n(#{hidden_count} more field(s) hidden, use -A to show all or -F to select)"
+        end
+        result
+      end
+
+      # Formats a hash as key-value pairs with recursive indentation
+      # for nested structures.
+      #
+      # @param hash [Hash] Hash to format
+      # @param show_empty [Boolean] Include fields with empty string values
+      def format_hash_table(hash, show_empty: false)
+        return '(empty)' if hash.empty?
+
+        format_hash_recursive(hash, 0, show_empty: show_empty)
+      end
+
+      # Recursively formats a hash with indentation for nested structures.
+      #
+      # @param hash [Hash] Hash to format
+      # @param indent [Integer] Current indentation level
+      # @param show_empty [Boolean] Include fields with empty string values
+      # @return [String] Formatted output
+      def format_hash_recursive(hash, indent, show_empty: false)
+        prefix = '  ' * indent
+        # Filter out empty string values unless show_empty is set
+        display_hash = show_empty ? hash : hash.reject { |_k, v| v.is_a?(String) && v.empty? }
+        return "#{prefix}(all fields empty)" if display_hash.empty?
+
+        max_key = display_hash.keys.map { |k| k.to_s.length }.max
+
+        display_hash.map do |k, v|
+          label = "#{prefix}#{k.to_s.ljust(max_key)}"
+          format_value_recursive(label, v, indent, show_empty: show_empty)
+        end.join("\n")
+      end
+
+      # Formats a single value, recursing into hashes and arrays.
+      #
+      # @param label [String] Pre-formatted "key" label with padding
+      # @param value [Object] Value to format
+      # @param indent [Integer] Current indentation level
+      # @param show_empty [Boolean] Include fields with empty string values
+      # @return [String] Formatted line(s)
+      def format_value_recursive(label, value, indent, show_empty: false)
+        case value
+        when Hash
+          if value.empty?
+            "#{label}  (empty)"
+          else
+            # Render nested hash on next lines with increased indent
+            "#{label}:\n#{format_hash_recursive(value, indent + 1, show_empty: show_empty)}"
+          end
+        when Array
+          if value.empty?
+            "#{label}  (none)"
+          else
+            # Render array items on next lines with increased indent
+            items = value.map { |item| format_array_item(item, indent + 1, show_empty: show_empty) }
+            "#{label}:\n#{items.join("\n")}"
+          end
+        else
+          "#{label}  #{value}"
+        end
+      end
+
+      # Formats a single array item with indentation.
+      #
+      # @param item [Object] Array element
+      # @param indent [Integer] Indentation level
+      # @param show_empty [Boolean] Include fields with empty string values
+      # @return [String] Formatted line(s)
+      def format_array_item(item, indent, show_empty: false)
+        prefix = '  ' * indent
+        case item
+        when Hash
+          # Render hash items with "- " prefix for first line
+          lines = format_hash_recursive(item, indent, show_empty: show_empty).split("\n")
+          first = lines.first&.sub(%r{\A#{Regexp.escape(prefix)}}, "#{prefix}- ")
+          rest = lines[1..]&.map { |l| "  #{l}" }
+          [first, *rest].compact.join("\n")
+        else
+          "#{prefix}- #{item}"
+        end
+      end
+
+      # Determines which keys to display based on filtering options.
+      #
+      # @param all_keys [Array<String>] All available column names
+      # @param fields [Array<String>, nil] Explicit field selection
+      # @param all_fields [Boolean] Show all fields
+      # @return [Array<String>] Keys to display
+      def select_display_keys(all_keys, fields: nil, all_fields: false)
+        if fields
+          # Explicit field selection: only show requested fields that exist
+          fields.select { |f| all_keys.include?(f) }
+        elsif all_fields || all_keys.length <= DEFAULT_MAX_FIELDS
+          all_keys
+        else
+          # Default: show first N fields
+          all_keys.first(DEFAULT_MAX_FIELDS)
+        end
+      end
+    end
+  end
+end

data/lib/opn_api/cli/main.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require_relative 'formatter'
+require_relative 'commands/base'
+require_relative 'commands/api'
+require_relative 'commands/backup'
+require_relative 'commands/device'
+require_relative 'commands/plugin'
+require_relative 'commands/reconfigure'
+require_relative 'commands/resource'
+
+module OpnApi
+  module CLI
+    # Main CLI dispatcher. Parses global options, extracts the subcommand,
+    # and delegates to the appropriate command module.
+    module Main
+      COMMANDS = {
+        'backup' => { handler: Commands::Backup.method(:download), desc: 'Download config backup' },
+        'create' => { handler: Commands::Resource.method(:create), desc: 'Create resource' },
+        'delete' => { handler: Commands::Resource.method(:delete), desc: 'Delete resource' },
+        'devices' => { handler: Commands::Device.method(:list), desc: 'List configured devices' },
+        'get' => { handler: Commands::Api.method(:get), desc: 'GET request to API path' },
+        'groups' => { handler: Commands::Reconfigure.method(:groups), desc: 'List reconfigure groups' },
+        'install' => { handler: Commands::Plugin.method(:install), desc: 'Install plugin' },
+        'plugins' => { handler: Commands::Plugin.method(:list), desc: 'List installed plugins' },
+        'post' => { handler: Commands::Api.method(:post), desc: 'POST request to API path' },
+        'reconfigure' => { handler: Commands::Reconfigure.method(:run), desc: 'Trigger service reconfigure' },
+        'resources' => { handler: Commands::Resource.method(:list), desc: 'List known resource types' },
+        'search' => { handler: Commands::Resource.method(:search), desc: 'Search resources' },
+        'show' => { handler: Commands::Resource.method(:show), desc: 'Show single resource' },
+        'test' => { handler: Commands::Device.method(:test), desc: 'Test device connectivity' },
+        'uninstall' => { handler: Commands::Plugin.method(:uninstall), desc: 'Uninstall plugin' },
+        'update' => { handler: Commands::Resource.method(:update), desc: 'Update resource' },
+      }.freeze
+
+      module_function
+
+      # Main entry point for the CLI.
+      #
+      # @param argv [Array<String>] Command-line arguments
+      # @return [Integer] Exit code (0 = success, 1 = error)
+      def run(argv)
+        opts = parse_global_options(argv)
+
+        # Show help if no command given
+        if argv.empty?
+          show_help
+          return 0
+        end
+
+        command_name = argv.shift
+        command = COMMANDS[command_name]
+
+        unless command
+          warn("Unknown command: #{command_name}")
+          warn("Run 'opn-api --help' for usage information.")
+          return 1
+        end
+
+        # Configure logging level
+        OpnApi.logger = OpnApi::Logger.new(level: opts[:verbose] ? :debug : :info)
+
+        # Execute command and format output
+        result = command[:handler].call(argv, opts)
+        output = Formatter.format(result, format: opts[:format], fields: opts[:fields],
+                                          all_fields: opts[:all_fields],
+                                          show_empty: opts[:show_empty])
+        puts output unless output.nil? || output.empty?
+
+        0
+      rescue OpnApi::ApiError => e
+        # Show full API response for debugging
+        warn("Error: #{e.message}")
+        warn("Response body: #{e.body}") if opts[:verbose] && e.body && !e.body.empty?
+        1
+      rescue OpnApi::Error => e
+        warn("Error: #{e.message}")
+        1
+      rescue JSON::ParserError => e
+        warn("Invalid JSON: #{e.message}")
+        1
+      end
+
+      # Parses global options from argv (modifies argv in place).
+      def parse_global_options(argv)
+        opts = { device: 'default', format: :table, verbose: false }
+
+        parser = OptionParser.new do |o|
+          o.banner = 'Usage: opn-api [options] <command> [command-options] [args...]'
+          o.separator ''
+          o.separator 'Global options:'
+
+          o.on('-c', '--config-dir PATH', 'Config directory for device files') do |v|
+            opts[:config_dir] = v
+          end
+          o.on('-d', '--device NAME', 'Device name (default: "default")') do |v|
+            opts[:device] = v
+          end
+          o.on('-f', '--format FORMAT', %w[table json yaml],
+               'Output format: table, json, yaml (default: table)') do |v|
+            opts[:format] = v.to_sym
+          end
+          o.on('-F', '--fields FIELDS', 'Comma-separated field names for table output') do |v|
+            opts[:fields] = v.split(',').map(&:strip)
+          end
+          o.on('-A', '--all-fields', 'Show all fields in table output (default: first 5)') do
+            opts[:all_fields] = true
+          end
+          o.on('-E', '--show-empty', 'Show empty fields in table output (default: hidden)') do
+            opts[:show_empty] = true
+          end
+          o.on('-v', '--verbose', 'Enable debug output') do
+            opts[:verbose] = true
+          end
+          o.on('--version', 'Show version') do
+            puts "opn-api #{OpnApi::VERSION}"
+            exit 0
+          end
+          o.on('-h', '--help', 'Show help') do
+            show_help
+            exit 0
+          end
+        end
+
+        # Parse global options from anywhere in argv (before or after command)
+        parser.parse!(argv)
+        opts
+      end
+
+      # Displays help with available commands.
+      def show_help
+        puts 'Usage: opn-api [options] <command> [command-options] [args...]'
+        puts ''
+        puts 'A CLI tool for the OPNsense REST API.'
+        puts ''
+        puts 'Global options:'
+        puts '  -c, --config-dir PATH    Config directory for device files'
+        puts '  -d, --device NAME        Device name (default: "default")'
+        puts '  -f, --format FORMAT      Output format: table, json, yaml (default: table)'
+        puts '  -F, --fields FIELDS      Comma-separated field names for table output'
+        puts '  -A, --all-fields         Show all fields in table output (default: first 5)'
+        puts '  -E, --show-empty         Show empty fields in table output (default: hidden)'
+        puts '  -v, --verbose            Enable debug output (includes API error details)'
+        puts '  --version                Show version'
+        puts '  -h, --help               Show this help'
+        puts ''
+        puts 'Commands:'
+        max_len = COMMANDS.keys.map(&:length).max
+        COMMANDS.each do |name, cmd|
+          puts "  #{name.ljust(max_len)}  #{cmd[:desc]}"
+        end
+        puts ''
+        puts 'Resource commands (search, show, create, update, delete) accept a resource'
+        puts 'name from the registry (e.g. "haproxy_server") or raw module/controller/type.'
+        puts 'Run "opn-api resources" for a list of known resource types.'
+      end
+    end
+  end
+end

data/lib/opn_api/client.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+require 'openssl'
+
+module OpnApi
+  # HTTP client for communicating with the OPNsense REST API.
+  #
+  # Supports SSL, redirect following (301/302/307/308), configurable
+  # timeouts, and basic authentication with API key/secret.
+  #
+  # @example Direct instantiation
+  #   client = OpnApi::Client.new(
+  #     url: 'https://fw.example.com/api',
+  #     api_key: '+ABC...', api_secret: '+XYZ...',
+  #     ssl_verify: false,
+  #   )
+  #   result = client.get('firmware/info/running')
+  #
+  # @example From Config
+  #   config = OpnApi::Config.new
+  #   client = config.client_for('myfw')
+  class Client
+    DEFAULT_URL = 'http://localhost:80/api'
+    MAX_REDIRECTS = 5
+
+    # @param url [String] Base URL of the OPNsense API (e.g. 'https://fw.example.com/api')
+    # @param api_key [String] OPNsense API key
+    # @param api_secret [String] OPNsense API secret
+    # @param ssl_verify [Boolean] Whether to verify SSL certificates (default: true)
+    # @param timeout [Integer] HTTP timeout in seconds (default: 60)
+    def initialize(url:, api_key:, api_secret:, ssl_verify: true, timeout: 60)
+      @url        = url.to_s.chomp('/')
+      @api_key    = api_key
+      @api_secret = api_secret
+      @ssl_verify = ssl_verify
+      @timeout    = timeout.to_i
+    end
+
+    # Performs an HTTP GET request to the OPNsense API.
+    #
+    # @param path [String] API path (relative, e.g. 'firewall/alias/search_item')
+    # @param raw [Boolean] If true, return raw response body instead of parsing JSON
+    # @return [Hash, String] Parsed JSON response, or raw body string when raw: true
+    def get(path, raw: false)
+      uri = build_uri(path)
+      OpnApi.logger.debug("GET #{uri}")
+      http_request(:get, uri, nil, 0, raw: raw)
+    end
+
+    # Performs an HTTP POST request to the OPNsense API.
+    #
+    # @param path [String] API path (relative)
+    # @param data [Hash] Request body (serialized as JSON)
+    # @return [Hash] Parsed JSON response
+    def post(path, data = {})
+      uri = build_uri(path)
+      OpnApi.logger.debug("POST #{uri} body=#{data.to_json}")
+      http_request(:post, uri, data)
+    end
+
+    private
+
+    # Executes an HTTP request, following redirects transparently.
+    # OPNsense commonly issues 308 redirects when HTTP is used but HTTPS is required.
+    #
+    # @param method [Symbol] :get or :post
+    # @param uri [URI] Fully qualified URI
+    # @param data [Hash, nil] POST body data
+    # @param redirect_count [Integer] Internal redirect counter
+    # @param raw [Boolean] If true, return raw response body instead of parsing JSON
+    # @return [Hash, String] Parsed JSON response, or raw body string when raw: true
+    def http_request(method, uri, data = nil, redirect_count = 0, raw: false)
+      if redirect_count > MAX_REDIRECTS
+        raise OpnApi::ConnectionError, "Too many redirects (> #{MAX_REDIRECTS}) for '#{uri}'"
+      end
+
+      http = build_http(uri)
+      request = build_request(method, uri, data)
+      request.basic_auth(@api_key, @api_secret)
+      request['Accept'] = 'application/json'
+      request['Content-Type'] = 'application/json' if method == :post
+
+      response = http.request(request)
+      code = response.code.to_i
+
+      # Handle redirects: 307/308 preserve method+body, 301/302 switch to GET
+      if [301, 302, 307, 308].include?(code)
+        location = response['location']
+        unless location
+          raise OpnApi::ConnectionError,
+                "#{code} redirect with no Location header for '#{uri}'"
+        end
+
+        OpnApi.logger.debug("Following #{code} redirect to '#{location}'")
+        new_uri = URI.parse(location)
+
+        if [307, 308].include?(code)
+          return http_request(method, new_uri, data, redirect_count + 1, raw: raw)
+        end
+
+        return http_request(:get, new_uri, nil, redirect_count + 1, raw: raw)
+      end
+
+      # Raw mode: skip JSON parsing, return body as string
+      return handle_raw_response(response, uri.to_s) if raw
+
+      handle_response(response, uri.to_s)
+    rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ETIMEDOUT => e
+      raise OpnApi::ConnectionError, "Connection failed for '#{uri}': #{e.message}"
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      raise OpnApi::TimeoutError, "Timeout for '#{uri}': #{e.message}"
+    end
+
+    # Builds a full URI from the base URL and a relative path.
+    def build_uri(path)
+      clean_path = path.to_s.sub(%r{^/+}, '')
+      URI.parse("#{@url}/#{clean_path}")
+    rescue URI::InvalidURIError => e
+      raise OpnApi::ConnectionError, "Invalid API path '#{path}': #{e.message}"
+    end
+
+    # Creates a Net::HTTP instance with SSL and timeout settings.
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+
+      if uri.scheme == 'https'
+        http.use_ssl = true
+        http.verify_mode = @ssl_verify ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+      end
+
+      http
+    end
+
+    # Builds a Net::HTTP request object for the given method.
+    def build_request(method, uri, data)
+      case method
+      when :get
+        Net::HTTP::Get.new(uri)
+      when :post
+        req = Net::HTTP::Post.new(uri)
+        req.body = data.to_json
+        req
+      else
+        raise ArgumentError, "Unsupported HTTP method: #{method}"
+      end
+    end
+
+    # Returns raw response body after checking HTTP status.
+    # Used for non-JSON endpoints (e.g. XML backup downloads).
+    #
+    # @param response [Net::HTTPResponse]
+    # @param request_uri [String]
+    # @return [String] Raw response body
+    def handle_raw_response(response, request_uri)
+      code = response.code.to_i
+      unless (200..299).cover?(code)
+        raise OpnApi::ApiError.new(
+          "API error #{code} for '#{request_uri}': #{response.body}",
+          code: code,
+          body: response.body.to_s,
+          uri: request_uri,
+        )
+      end
+
+      OpnApi.logger.debug("Response #{code} (raw, #{response.body.to_s.bytesize} bytes)")
+      response.body.to_s
+    end
+
+    # Parses and validates an HTTP response.
+    #
+    # @param response [Net::HTTPResponse]
+    # @param request_uri [String]
+    # @return [Hash] Parsed JSON body
+    def handle_response(response, request_uri)
+      code = response.code.to_i
+      unless (200..299).cover?(code)
+        raise OpnApi::ApiError.new(
+          "API error #{code} for '#{request_uri}': #{response.body}",
+          code: code,
+          body: response.body.to_s,
+          uri: request_uri,
+        )
+      end
+
+      body = response.body
+      return {} if body.nil? || body.strip.empty?
+
+      OpnApi.logger.debug("Response #{code} body=#{body.strip}")
+      JSON.parse(body)
+    rescue JSON::ParserError => e
+      raise OpnApi::ApiError.new(
+        "Response parse error for '#{request_uri}': #{e.message}",
+        code: code,
+        body: body.to_s,
+        uri: request_uri,
+      )
+    end
+  end
+end

data/lib/opn_api/config.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module OpnApi
+  # Configuration loader for OPNsense device credentials.
+  #
+  # Searches for per-device YAML files in a config directory hierarchy.
+  # Each YAML file contains connection details for one OPNsense device.
+  #
+  # Search order (lowest → highest priority):
+  # 1. /etc/opn-api/devices/          (system-wide)
+  # 2. ~/.config/opn-api/devices/     (per-user)
+  # 3. Explicit config_dir parameter  (programmatic / CLI)
+  # 4. OPN_API_CONFIG_DIR env var     (environment override)
+  #
+  # Device YAML format (compatible with puppet-opn):
+  #   url: https://192.168.1.1/api
+  #   api_key: +ABC...
+  #   api_secret: +XYZ...
+  #   ssl_verify: false
+  #   timeout: 60
+  #
+  # @example
+  #   config = OpnApi::Config.new
+  #   config.device_names            # => ['myfw', 'backup']
+  #   client = config.client_for('myfw')
+  #
+  # @example With explicit path (e.g. for puppet-opn integration)
+  #   config = OpnApi::Config.new(config_dir: '/etc/puppetlabs/puppet/opn')
+  #   client = config.client_for('myfw')
+  class Config
+    SYSTEM_DIR = '/etc/opn-api/devices'
+    USER_DIR   = File.join(Dir.home, '.config', 'opn-api', 'devices')
+
+    # @param config_dir [String, nil] Explicit device config directory.
+    #   Overrides the default search hierarchy (but not OPN_API_CONFIG_DIR).
+    def initialize(config_dir: nil)
+      @config_dir = resolve_config_dir(config_dir)
+    end
+
+    # Returns all available device names found in the config directory.
+    #
+    # @return [Array<String>] Sorted list of device names
+    def device_names
+      return [] unless @config_dir && Dir.exist?(@config_dir)
+
+      Dir.glob(File.join(@config_dir, '*.yaml')).map do |f|
+        File.basename(f, '.yaml')
+      end.sort
+    end
+
+    # Returns the configuration hash for a named device.
+    #
+    # @param name [String] Device name (filename without .yaml extension)
+    # @return [Hash] Device config (url, api_key, api_secret, ssl_verify, timeout)
+    # @raise [OpnApi::ConfigError] if config file is missing or malformed
+    def device(name)
+      path = device_path(name)
+      unless File.exist?(path)
+        raise OpnApi::ConfigError,
+              "Config file not found for device '#{name}': #{path}"
+      end
+
+      config = YAML.safe_load_file(path)
+      unless config.is_a?(Hash)
+        raise OpnApi::ConfigError,
+              "Config file '#{path}' is not a valid YAML hash"
+      end
+
+      config
+    end
+
+    # Creates a Client instance for the named device.
+    #
+    # @param name [String] Device name
+    # @return [OpnApi::Client]
+    # @raise [OpnApi::ConfigError] if config is missing or malformed
+    def client_for(name)
+      cfg = device(name)
+      OpnApi::Client.new(
+        url: cfg['url'] || OpnApi::Client::DEFAULT_URL,
+        api_key: cfg['api_key'].to_s,
+        api_secret: cfg['api_secret'].to_s,
+        ssl_verify: cfg.fetch('ssl_verify', true),
+        timeout: cfg.fetch('timeout', 60),
+      )
+    end
+
+    # Returns the full path to a device config file.
+    #
+    # @param name [String] Device name
+    # @return [String]
+    def device_path(name)
+      File.join(@config_dir, "#{name}.yaml")
+    end
+
+    private
+
+    # Resolves the effective config directory from env, explicit arg, or defaults.
+    # Priority: OPN_API_CONFIG_DIR > explicit config_dir > first existing default dir
+    def resolve_config_dir(explicit_dir)
+      env_dir = ENV.fetch('OPN_API_CONFIG_DIR', nil)
+      return env_dir if env_dir && !env_dir.empty?
+      return explicit_dir if explicit_dir
+
+      # Use the first default directory that exists, or fall back to USER_DIR
+      [USER_DIR, SYSTEM_DIR].find { |d| Dir.exist?(d) } || USER_DIR
+    end
+  end
+end