opn_api 0.1.0

data/bin/opn-api

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/opn_api'
+require_relative '../lib/opn_api/cli/main'
+
+exit OpnApi::CLI::Main.run(ARGV)

data/lib/opn_api/cli/commands/api.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module OpnApi
+  module CLI
+    module Commands
+      # CLI commands for generic API calls (GET/POST).
+      module Api
+        module_function
+
+        # Performs a GET request to an arbitrary API path.
+        #
+        # @param args [Array<String>] [path]
+        # @param opts [Hash] Global CLI options
+        # @return [Object] Parsed API response
+        def get(args, opts)
+          path = args.shift
+          raise OpnApi::Error, 'Usage: opn-api get <path>' unless path
+
+          client = Base.build_client(opts)
+          client.get(path)
+        end
+
+        # Performs a POST request to an arbitrary API path.
+        #
+        # @param args [Array<String>] [path, optional_json]
+        # @param opts [Hash] Global CLI options
+        # @return [Object] Parsed API response
+        def post(args, opts)
+          path = args.shift
+          raise OpnApi::Error, 'Usage: opn-api post <path> [json]' unless path
+
+          client = Base.build_client(opts)
+          data = parse_post_data(args)
+          client.post(path, data)
+        end
+
+        # Parses POST data from args or stdin.
+        def parse_post_data(args)
+          # Inline JSON argument
+          json_str = args.shift
+          return JSON.parse(json_str) if json_str
+
+          # Stdin
+          unless $stdin.tty?
+            input = $stdin.read.strip
+            return JSON.parse(input) unless input.empty?
+          end
+
+          # Default: empty body
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/opn_api/cli/commands/backup.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module OpnApi
+  module CLI
+    module Commands
+      # CLI command for downloading OPNsense config backups.
+      #
+      # The backup endpoint returns XML (not JSON), so this uses
+      # the client's raw mode to skip JSON parsing.
+      module Backup
+        module_function
+
+        # Downloads the OPNsense config backup (XML).
+        # Usage: opn-api backup [output_path]
+        #
+        # With output_path: writes XML to file, returns status hash.
+        # Without output_path: returns raw XML string (printed to stdout).
+        #
+        # @param args [Array<String>] [optional output_path]
+        # @param opts [Hash] Global CLI options
+        # @return [Hash, String] Status hash or raw XML data
+        def download(args, opts)
+          client = Base.build_client(opts)
+          data = client.get('core/backup/download/this', raw: true)
+
+          output_path = args.shift
+          if output_path
+            File.write(output_path, data)
+            { 'status' => 'ok', 'file' => output_path, 'size' => data.bytesize }
+          else
+            # Without output path: raw data directly to stdout
+            data
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opn_api/cli/commands/base.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module OpnApi
+  module CLI
+    module Commands
+      # Shared helpers for all CLI commands.
+      module Base
+        # Creates an OpnApi::Config from global options.
+        #
+        # @param opts [Hash] Global CLI options
+        # @return [OpnApi::Config]
+        def self.build_config(opts)
+          OpnApi::Config.new(config_dir: opts[:config_dir])
+        end
+
+        # Creates an OpnApi::Client for the device specified in global options.
+        #
+        # @param opts [Hash] Global CLI options (must include :device)
+        # @return [OpnApi::Client]
+        def self.build_client(opts)
+          config = build_config(opts)
+          config.client_for(opts[:device])
+        end
+
+        # Reads JSON input from -j argument or stdin.
+        #
+        # @param args [Array<String>] Remaining CLI args
+        # @return [Hash] Parsed JSON
+        def self.read_json_input(args)
+          # Check for -j flag in remaining args
+          json_idx = args.index('-j')
+          if json_idx
+            json_str = args[json_idx + 1]
+            raise OpnApi::Error, 'Missing JSON data after -j' unless json_str
+
+            return JSON.parse(json_str)
+          end
+
+          # Read from stdin if not a TTY
+          unless $stdin.tty?
+            input = $stdin.read.strip
+            return JSON.parse(input) unless input.empty?
+          end
+
+          raise OpnApi::Error, 'No JSON input provided (use -j or pipe via stdin)'
+        end
+      end
+    end
+  end
+end

data/lib/opn_api/cli/commands/device.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module OpnApi
+  module CLI
+    module Commands
+      # CLI commands for device management.
+      module Device
+        module_function
+
+        # Lists all configured devices.
+        #
+        # @param _args [Array<String>] Unused
+        # @param opts [Hash] Global CLI options
+        # @return [Object] Formatted output data
+        def list(_args, opts)
+          config = Base.build_config(opts)
+          names = config.device_names
+          return '(no devices configured)' if names.empty?
+
+          names.map { |n| { 'device' => n, 'config' => config.device_path(n) } }
+        end
+
+        # Tests connectivity to one or all devices.
+        #
+        # @param args [Array<String>] Optional device name
+        # @param opts [Hash] Global CLI options
+        # @return [Object] Formatted output data
+        def test(args, opts)
+          config = Base.build_config(opts)
+          names = args.empty? ? config.device_names : [args.first]
+          results = []
+
+          names.each do |name|
+            result = { 'device' => name }
+            begin
+              client = config.client_for(name)
+              # Call a lightweight endpoint to check connectivity
+              info = client.get('core/firmware/info')
+              result['status'] = 'ok'
+              result['version'] = info['product_version'].to_s if info['product_version']
+            rescue OpnApi::Error => e
+              result['status'] = 'error'
+              result['message'] = e.message
+            end
+            results << result
+          end
+
+          results
+        end
+      end
+    end
+  end
+end

data/lib/opn_api/cli/commands/plugin.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module OpnApi
+  module CLI
+    module Commands
+      # CLI commands for OPNsense plugin management.
+      #
+      # Plugins use the firmware API which does not follow the standard
+      # CRUD pattern. These commands provide a user-friendly interface.
+      module Plugin
+        module_function
+
+        # Lists installed plugins.
+        # Usage: opn-api plugins
+        #
+        # Fetches the firmware info and filters for installed os-* packages.
+        #
+        # @param _args [Array<String>] Unused
+        # @param opts [Hash] Global CLI options
+        # @return [Array<Hash>] List of installed plugins
+        def list(_args, opts)
+          client = Base.build_client(opts)
+          info = client.get('core/firmware/info')
+          packages = info['package'] || []
+
+          # Filter for installed plugin packages (os-* naming convention)
+          packages.select { |p| p['installed'] == '1' && p['name'].to_s.start_with?('os-') }
+                  .map do |p|
+                    {
+                      'name' => p['name'],
+                      'version' => p['version'],
+                      'comment' => p['comment'],
+                    }
+                  end
+        end
+
+        # Installs a plugin.
+        # Usage: opn-api install <plugin_name>
+        #
+        # @param args [Array<String>] [plugin_name]
+        # @param opts [Hash] Global CLI options
+        # @return [Hash] API response
+        def install(args, opts)
+          name = args.shift
+          raise OpnApi::Error, 'Usage: opn-api install <plugin_name>' unless name
+
+          client = Base.build_client(opts)
+          client.post("core/firmware/install/#{name}", {})
+        end
+
+        # Uninstalls a plugin.
+        # Usage: opn-api uninstall <plugin_name>
+        #
+        # @param args [Array<String>] [plugin_name]
+        # @param opts [Hash] Global CLI options
+        # @return [Hash] API response
+        def uninstall(args, opts)
+          name = args.shift
+          raise OpnApi::Error, 'Usage: opn-api uninstall <plugin_name>' unless name
+
+          client = Base.build_client(opts)
+          client.post("core/firmware/remove/#{name}", {})
+        end
+      end
+    end
+  end
+end

data/lib/opn_api/cli/commands/reconfigure.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module OpnApi
+  module CLI
+    module Commands
+      # CLI commands for service reconfigure operations.
+      module Reconfigure
+        module_function
+
+        # Lists all registered reconfigure groups.
+        #
+        # @param _args [Array<String>] Unused
+        # @param _opts [Hash] Unused
+        # @return [Array<Hash>] Group information
+        def groups(_args, _opts)
+          OpnApi::ServiceReconfigure.registered_names.sort.map do |name|
+            OpnApi::ServiceReconfigure[name]
+            { 'group' => name.to_s }
+          end
+        end
+
+        # Triggers reconfigure for a specific group on a device.
+        # Usage: opn-api reconfigure <group>
+        #
+        # @param args [Array<String>] [group_name]
+        # @param opts [Hash] Global CLI options
+        # @return [Hash] Reconfigure results
+        def run(args, opts)
+          group_name = args.shift
+          raise OpnApi::Error, 'Usage: opn-api reconfigure <group>' unless group_name
+
+          client = Base.build_client(opts)
+          group = OpnApi::ServiceReconfigure[group_name.to_sym]
+          group.mark(opts[:device], client)
+          group.run
+        end
+      end
+    end
+  end
+end

data/lib/opn_api/cli/commands/resource.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module OpnApi
+  module CLI
+    module Commands
+      # CLI commands for structured resource CRUD operations.
+      #
+      # Resources can be specified in two ways:
+      # 1. Registry name (preferred): opn-api search haproxy_server
+      # 2. Raw module/controller/type: opn-api search haproxy settings search_servers
+      #
+      # The registry handles the inconsistent OPNsense endpoint naming
+      # (plural search, camelCase, bare names) transparently.
+      #
+      # Singleton resources (settings) are auto-detected from the registry
+      # and work without UUID for show/update.
+      module Resource
+        module_function
+
+        # Searches for resources.
+        # Usage: opn-api search <resource_name>
+        #        opn-api search <module> <controller> <type>
+        #
+        # @param args [Array<String>] Resource name or [module, controller, type]
+        # @param opts [Hash] Global CLI options
+        # @return [Object] Search results
+        def search(args, opts)
+          resource_name = args.first
+          res = build_resource(args, opts, 'search')
+          result = res.search
+          return result unless res.singleton
+
+          # Singleton: unwrap, filter, normalize (same as show)
+          result = result.values.first if result.is_a?(Hash) && result.length == 1 && result.values.first.is_a?(Hash)
+          result = filter_singleton_response(resource_name, result) if result.is_a?(Hash)
+          OpnApi::Normalize.normalize_config(result)
+        end
+
+        # Shows a single resource by UUID, or a singleton settings resource.
+        # Usage: opn-api show <resource_name> <uuid>
+        #        opn-api show <singleton_resource>
+        #
+        # @param args [Array<String>] Resource name + uuid, or singleton name
+        # @param opts [Hash] Global CLI options
+        # @return [Hash] Resource data
+        def show(args, opts)
+          # Capture resource name before it's shifted from args
+          resource_name = args.first
+          res, remaining = build_resource_with_remainder(args, opts, 'show')
+
+          result = if res.singleton
+                     res.show_settings
+                   else
+                     uuid = remaining.shift
+                     raise OpnApi::Error, "Usage: opn-api show <resource> <uuid>\n#{registry_hint}" unless uuid
+
+                     res.get(uuid)
+                   end
+
+          # Unwrap single-key response (e.g. {"alias": {...}} → inner hash)
+          result = result.values.first if result.is_a?(Hash) && result.length == 1 && result.values.first.is_a?(Hash)
+
+          # Filter singleton response to settings-only keys (matching puppet-opn behavior)
+          result = filter_singleton_response(resource_name, result) if res.singleton && result.is_a?(Hash)
+
+          # Normalize selection hashes for human-readable output
+          OpnApi::Normalize.normalize_config(result)
+        end
+
+        # Creates a new resource.
+        # Usage: opn-api create <resource_name> [-j json | stdin]
+        #
+        # @param args [Array<String>] Resource name, then JSON
+        # @param opts [Hash] Global CLI options
+        # @return [Hash] API response
+        def create(args, opts)
+          res, remaining = build_resource_with_remainder(args, opts, 'create')
+          raise OpnApi::Error, 'Singleton resources do not support create. Use update instead.' if res.singleton
+
+          data = Base.read_json_input(remaining)
+          result = res.add(data)
+          check_result(result, 'create', args)
+          result
+        end
+
+        # Updates an existing resource by UUID, or a singleton settings resource.
+        # Usage: opn-api update <resource_name> <uuid> [-j json | stdin]
+        #        opn-api update <singleton_resource> [-j json | stdin]
+        #
+        # @param args [Array<String>] Resource + uuid, then JSON
+        # @param opts [Hash] Global CLI options
+        # @return [Hash] API response
+        def update(args, opts)
+          res, remaining = build_resource_with_remainder(args, opts, 'update')
+
+          if res.singleton
+            data = Base.read_json_input(remaining)
+            result = res.update_settings(data)
+          else
+            uuid = remaining.shift
+            raise OpnApi::Error, "Usage: opn-api update <resource> <uuid> -j '<json>'" unless uuid
+
+            data = Base.read_json_input(remaining)
+            result = res.set(uuid, data)
+          end
+
+          check_result(result, 'update', args)
+          result
+        end
+
+        # Deletes a resource by UUID.
+        # Usage: opn-api delete <resource_name> <uuid>
+        #
+        # @param args [Array<String>] Resource + uuid
+        # @param opts [Hash] Global CLI options
+        # @return [Hash] API response
+        def delete(args, opts)
+          res, remaining = build_resource_with_remainder(args, opts, 'delete')
+          raise OpnApi::Error, 'Singleton resources do not support delete.' if res.singleton
+
+          uuid = remaining.shift
+          raise OpnApi::Error, 'Usage: opn-api delete <resource> <uuid>' unless uuid
+
+          result = res.del(uuid)
+          check_result(result, 'delete', args)
+          result
+        end
+
+        # Lists all known resource types from the registry.
+        # Usage: opn-api resources
+        #
+        # @param _args [Array<String>] Unused
+        # @param _opts [Hash] Unused
+        # @return [Array<Hash>] Resource type information
+        def list(_args, _opts)
+          OpnApi::ResourceRegistry.names.map do |name|
+            entry = OpnApi::ResourceRegistry.lookup(name)
+            type = entry[:singleton] ? 'singleton' : 'crud'
+            { 'resource' => name, 'wrapper_key' => entry[:wrapper].to_s, 'type' => type }
+          end
+        end
+
+        # Checks the API result for failure and raises with the full API response.
+        def check_result(result, action, args)
+          return unless result.is_a?(Hash)
+
+          status = (result['result'] || result['status']).to_s.strip.downcase
+          return unless status == 'failed'
+
+          msg = "#{action} failed: #{JSON.generate(result)}"
+
+          # When OPNsense returns only {"result":"failed"} without validation
+          # details, the most common cause is a wrong wrapper key in the JSON body.
+          if result.keys == ['result']
+            wrapper_hint = detect_wrapper_key(args)
+            msg += "\nHint: The JSON wrapper key is likely wrong. "
+            msg += "Expected wrapper key: '#{wrapper_hint}'. " if wrapper_hint
+            msg += 'The endpoint type is NOT the wrapper key. ' unless wrapper_hint
+            msg += 'Use "opn-api show -f json" on an existing resource to find the correct wrapper key. '
+            msg += 'Use -v for full request/response details.'
+          end
+
+          raise OpnApi::Error, msg
+        end
+
+        # Tries to detect the correct wrapper key from args.
+        def detect_wrapper_key(args)
+          name = args.is_a?(Array) ? args.first : nil
+          return nil unless name
+
+          entry = OpnApi::ResourceRegistry.lookup(name)
+          entry&.dig(:wrapper)
+        end
+
+        # Builds a Resource from args.
+        def build_resource(args, opts, command)
+          build_resource_with_remainder(args, opts, command).first
+        end
+
+        # Builds a Resource and returns [resource, remaining_args].
+        # Tries registry lookup first, then raw mode.
+        def build_resource_with_remainder(args, opts, command)
+          raise OpnApi::Error, "Usage: opn-api #{command} <resource>\n#{registry_hint}" if args.empty?
+
+          client = Base.build_client(opts)
+
+          # Try registry lookup (single arg)
+          entry = OpnApi::ResourceRegistry.lookup(args.first)
+          if entry
+            name = args.shift
+            res = OpnApi::ResourceRegistry.build(client, name)
+            return [res, args]
+          end
+
+          # Fallback: raw module/controller/type (three args)
+          if args.length >= 3 && !args[0].start_with?('-')
+            mod = args.shift
+            ctrl = args.shift
+            type = args.shift
+            res = OpnApi::Resource.new(
+              client: client,
+              module_name: mod,
+              controller: ctrl,
+              resource_type: type,
+            )
+            return [res, args]
+          end
+
+          raise OpnApi::Error,
+                "Unknown resource: '#{args.first}'. " \
+                "Run 'opn-api resources' for known types, or use three args: <module> <controller> <type>"
+        end
+
+        # Filters a singleton response to only include settings keys,
+        # excluding sub-resource data. Matches puppet-opn behavior:
+        # - response_dig with 1 element → dig into that sub-key
+        # - response_dig with 2+ elements → slice those keys
+        # - response_reject → reject those keys
+        # - neither → return unfiltered
+        def filter_singleton_response(resource_name, result)
+          entry = OpnApi::ResourceRegistry.lookup(resource_name)
+          return result unless entry
+
+          if entry[:response_dig]
+            keys = entry[:response_dig]
+            if keys.length == 1
+              # Single key: dig into sub-key (e.g. acmeclient → settings)
+              result[keys.first] || result
+            else
+              # Multiple keys: slice those settings sections
+              result.slice(*keys)
+            end
+          elsif entry[:response_reject]
+            # Reject sub-resource keys (e.g. zabbix_agent → reject aliases, userparameters)
+            result.except(*entry[:response_reject])
+          else
+            result
+          end
+        end
+
+        # Hint text for error messages.
+        def registry_hint
+          "Run 'opn-api resources' for a list of known resource types."
+        end
+      end
+    end
+  end
+end