add support for Puppet Agent API endpoint

Author: fraenki

README.md

@@ -27,6 +27,7 @@ A Ruby client library and CLI tool for the OPNsense REST API.
     - [Node Exporter](#node-exporter)
     - [OpenVPN](#openvpn)
     - [Plugins](#plugins)
+    - [Puppet Agent](#puppet-agent)
     - [Routes](#routes)
     - [Service reconfigure](#service-reconfigure-1)
     - [Snapshots](#snapshots)
@@ -121,6 +122,7 @@ Backups and plugins are managed separately via dedicated commands (`backup`, `pl
 | `openvpn_cso` | OpenVPN client-specific overrides |
 | `openvpn_instance` | OpenVPN instances |
 | `openvpn_statickey` | OpenVPN static keys |
+| `puppet_agent` | Puppet Agent settings (singleton) |
 | `route` | Static routes |
 | `snapshot` | ZFS snapshots |
 | `syslog` | Syslog remote destinations |
@@ -607,6 +609,22 @@ $ opn-api -d opnsense01 uninstall os-haproxy
 
 Note: Install/uninstall are asynchronous — the API returns immediately while the operation continues in the background.
 
+### Puppet Agent
+
+Puppet Agent is a singleton resource (one per device).
+
+```
+# Show Puppet Agent settings (singleton)
+$ opn-api -d opnsense01 show puppet_agent
+
+# Update Puppet Agent settings (wrapper key: "puppetagent")
+$ opn-api -d opnsense01 update puppet_agent \
+    -j '{"puppetagent":{"general":{"Enabled":"1","FQDN":"puppet.example.com","Environment":"production"}}}'
+
+# Apply changes
+$ opn-api -d opnsense01 reconfigure puppet_agent
+```
+
 ### Routes
 
 ```
@@ -962,7 +980,7 @@ Resource names follow the [puppet-opn](https://github.com/markt-de/puppet-opn) n
 
 `OpnApi::ServiceReconfigure` orchestrates service reloads after configuration changes. Features include:
 
-- Registry pattern with 18 pre-registered OPNsense service groups
+- Registry pattern with many pre-registered OPNsense service groups
 - Mark/run pattern: track devices with changes, then batch-reconfigure
 - Configtest support (e.g. HAProxy validates config before reconfigure)
 - Error tracking: skip reconfigure for devices with failed resource changes

lib/opn_api/resource_registry.rb

@@ -259,6 +259,13 @@ module ResourceRegistry
         crud_action: '%{action}', wrapper: 'general',
         singleton: true, search_method: :get
       },
+      # --- Puppet Agent ---
+      'puppet_agent' => {
+        base_path: 'puppetagent/settings', search_action: 'get',
+        crud_action: '%{action}', wrapper: 'puppetagent',
+        singleton: true, search_method: :get,
+        response_dig: ['general']
+      },
       # --- OpenVPN ---
       'openvpn_cso' => {
         base_path: 'openvpn/client_overwrites', search_action: 'search',

lib/opn_api/service_reconfigure.rb

@@ -258,6 +258,11 @@ def self.register_defaults
                endpoint: 'nodeexporter/service/reconfigure',
                log_prefix: 'opn_node_exporter')
 
+      # Puppet Agent
+      register(:puppet_agent,
+               endpoint: 'puppetagent/service/reconfigure',
+               log_prefix: 'opn_puppet_agent')
+
       # OpenVPN
       register(:openvpn,
                endpoint: 'openvpn/service/reconfigure',

spec/opn_api/resource_registry_spec.rb

@@ -50,6 +50,8 @@
     it 'provides response_dig for singletons with sub-resources' do
       # Single sub-key extraction (acmeclient settings nested under 'settings')
       expect(described_class.lookup('acmeclient_settings')[:response_dig]).to eq(['settings'])
+      # Single sub-key extraction (puppet_agent settings nested under 'general')
+      expect(described_class.lookup('puppet_agent')[:response_dig]).to eq(['general'])
       # Multi-key slice (haproxy, ipsec, kea)
       expect(described_class.lookup('ipsec_settings')[:response_dig]).to eq(%w[general charon])
       expect(described_class.lookup('kea_dhcpv4')[:response_dig]).to eq(%w[general lexpire ha])
@@ -69,6 +71,15 @@
       expect(described_class.lookup('zabbix_proxy')[:response_dig]).to be_nil
     end
 
+    it 'handles puppet_agent singleton with settings controller' do
+      entry = described_class.lookup('puppet_agent')
+      expect(entry[:base_path]).to eq('puppetagent/settings')
+      expect(entry[:singleton]).to be true
+      expect(entry[:search_method]).to eq(:get)
+      expect(entry[:wrapper]).to eq('puppetagent')
+      expect(entry[:response_dig]).to eq(['general'])
+    end
+
     it 'handles Kea camelCase endpoints' do
       entry = described_class.lookup('kea_dhcpv4_subnet')
       expect(entry[:base_path]).to eq('kea/dhcpv4')
@@ -118,6 +129,7 @@
         'kea_dhcpv6', 'kea_dhcpv6_pd_pool',
         'node_exporter',
         'openvpn_instance', 'openvpn_cso', 'openvpn_statickey',
+        'puppet_agent',
         'route', 'snapshot', 'syslog',
         'trust_ca', 'trust_cert', 'trust_crl',
         'tunable', 'user',

spec/opn_api/service_reconfigure_spec.rb

@@ -38,7 +38,8 @@
       described_class.load_defaults!
       names = described_class.registered_names
       expect(names).to include(:haproxy, :ipsec, :openvpn, :kea, :firewall_alias,
-                               :firewall_rule, :cron, :dhcrelay, :gateway, :route)
+                               :firewall_rule, :cron, :dhcrelay, :gateway,
+                               :puppet_agent, :route)
     end
   end