dnsmadeeasy 0.4.0 → 1.0.1

data/docs/spec-zone-management.md

@@ -0,0 +1,242 @@
+# DNS Zone Management Specification
+
+## Overview
+
+Extend the existing `dnsmadeeasy` Ruby gem with first-class support for managing DNS zones using standard RFC 1034/1035 zone files.
+
+The objective is to make zone files the source of truth while continuing to use the existing DNS Made Easy API client for all provider interactions.
+
+This feature is intentionally **DNS Made Easy specific**. It does not attempt to become a generic multi-provider framework.
+
+______________________________________________________________________
+
+# Goals
+
+- Use standard DNS zone files.
+- Produce deterministic, Git-friendly output.
+- Generate human-readable execution plans.
+- Apply the minimum set of API changes.
+- Be safe by default.
+- Be easy for LLMs to generate and modify.
+
+______________________________________________________________________
+
+# Existing Foundation
+
+The gem already provides:
+
+- authentication
+- domain lookup
+- record enumeration
+- create/update/delete operations
+- YAML/JSON output
+- CLI
+
+The new functionality builds on these capabilities rather than replacing them.
+
+______________________________________________________________________
+
+# Architecture
+
+```
+          Zone File
+              │
+              ▼
+     DNS::Zonefile.load
+      (dns-zonefile gem)
+              │
+              ▼
+      Internal Record Model
+              │
+              ├─────────────┐
+              │             │
+              ▼             ▼
+      dme all DOMAIN    Zone File
+      (remote state)    Serializer
+              │
+              ▼
+         Diff Engine
+              │
+              ▼
+      Execution Plan
+              │
+              ▼
+     Existing API Client
+```
+
+______________________________________________________________________
+
+# Dependency
+
+Use the `dns-zonefile` gem solely for parsing RFC-compliant zone files.
+
+The rest of the implementation should not depend directly on `DNS::Zonefile::*` classes.
+
+Instead:
+
+```
+Zone File
+    │
+    ▼
+Parser Adapter
+    │
+    ▼
+DnsMadeEasy::Zone::Record
+```
+
+This isolates the rest of the implementation from parser details.
+
+______________________________________________________________________
+
+# Canonical Zone File
+
+Exports should produce a normalized zone file.
+
+Characteristics:
+
+- one zone per file
+- explicit owner on every record
+- `$ORIGIN`
+- `$TTL`
+- `@` for zone apex
+- deterministic ordering
+- normalized whitespace
+- provider-managed SOA omitted
+- apex NS records omitted by default
+- delegated NS records preserved
+
+Example:
+
+```dns
+$ORIGIN example.com.
+$TTL 300
+
+@       IN A       203.0.113.10
+www     IN CNAME   @
+
+@       IN MX      10 mail.example.com.
+
+@       IN TXT     "v=spf1 include:_spf.google.com ~all"
+```
+
+______________________________________________________________________
+
+# New Commands
+
+```
+dme zone export DOMAIN
+```
+
+Download remote records and emit a canonical zone file.
+
+```
+dme zone validate FILE
+```
+
+Validate syntax and supported record types.
+
+```
+dme zone fmt FILE
+```
+
+Rewrite the file into canonical formatting.
+
+```
+dme zone plan FILE
+```
+
+Compare desired state against the provider and display the planned actions.
+
+```
+dme zone apply FILE
+```
+
+Execute the planned changes.
+
+______________________________________________________________________
+
+# Internal Record Model
+
+The diff engine operates on an internal provider-neutral record model.
+
+Provider-specific metadata (record IDs, source IDs, etc.) is stored separately and is never serialized into zone files.
+
+______________________________________________________________________
+
+# Diff Semantics
+
+Default behavior:
+
+- create missing records
+- update modified records
+- never delete records
+
+Future option:
+
+```
+dme zone apply FILE --delete
+```
+
+removes remote records not present in the zone file (excluding protected provider-managed records).
+
+______________________________________________________________________
+
+# Export Rules
+
+Export should normalize:
+
+- empty owner → `@`
+- relative owner names
+- TTLs
+- whitespace
+- ordering
+
+Repeated export of an unchanged zone should produce byte-identical output.
+
+______________________________________________________________________
+
+# Provider-specific Records
+
+HTTPRED cannot be represented in a standard RFC zone file.
+
+Version 1 behavior:
+
+- omit HTTPRED records from exports
+- emit a warning listing omitted records
+
+Future versions may support provider-specific comment directives.
+
+______________________________________________________________________
+
+# LLM Workflow
+
+The intended AI workflow is:
+
+```
+User request
+      │
+      ▼
+LLM edits zone file
+      │
+      ▼
+dme zone plan
+      │
+      ▼
+Human reviews plan
+      │
+      ▼
+dme zone apply
+```
+
+The LLM never calls provider APIs directly.
+
+______________________________________________________________________
+
+# Non-goals
+
+- Multi-provider abstraction
+- Inventing a new configuration language
+- Replacing existing DNS tooling
+- Supporting every obscure BIND extension
+
+The project embraces standard DNS zone files and extends the existing `dnsmadeeasy` gem with a modern declarative workflow.

data/exe/dme

@@ -1,6 +1,17 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'dnsmadeeasy/runner'
+require 'dnsmadeeasy'
+require 'dnsmadeeasy/cli/message_helpers'
 
-DnsMadeEasy::Runner.new(ARGV).execute!
+# CLI for DnsMadeEasy v1
+# @deprecated use dmez instead
+class DmeCli
+  def self.start
+    puts
+    ::DnsMadeEasy::CLI::MessageHelpers.error("You've upgraded to the version #{DnsMadeEasy::VERSION} of the DnsMadeEasy Ruby Gem.\nPlease use the new 'dmez' CLI command instead.")
+    exit 1
+  end
+end
+
+DmeCli.start

data/exe/dmez

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'dnsmadeeasy'
+
+exit(DnsMadeEasy::CLI::Launcher.new(ARGV.dup).execute!)

data/lib/dme.rb

@@ -7,10 +7,15 @@ module DME
     def [](key, secret)
       ::DnsMadeEasy::Api::Client.new(key, secret)
     end
-    def method_missing(method, *args, &block)
-      DnsMadeEasy.send(method, *args, &block)
+
+    def method_missing(method, ...)
+      DnsMadeEasy.send(method, ...)
     rescue NameError => e
       puts "Error: #{e.message}"
     end
+
+    def respond_to_missing?(method, include_private = false)
+      DnsMadeEasy.respond_to?(method, include_private) || super
+    end
   end
 end

data/lib/dnsmadeeasy/api/client.rb

@@ -13,7 +13,7 @@ module DnsMadeEasy
     class Client
       class << self
         def public_operations
-          (new('a', 'b').methods - Object.methods).map(&:to_s).reject { |r| r =~ /[=]$|^(api_|on_|request)/ }.sort
+          (new('a', 'b').methods - Object.methods).map(&:to_s).reject { |r| r =~ /=$|^(api_|on_|request)/ }.sort
         end
       end
 
@@ -24,8 +24,8 @@ module DnsMadeEasy
                   :api_secret
 
       def initialize(api_key, api_secret, sandbox = false, options = {})
-        fail 'api_key is undefined' unless api_key
-        fail 'api_secret is undefined' unless api_secret
+        raise 'api_key is undefined' unless api_key
+        raise 'api_secret is undefined' unless api_secret
 
         @api_key            = api_key
         @api_secret         = api_secret
@@ -36,12 +36,12 @@ module DnsMadeEasy
         sandbox ? on_sandbox : on_production
       end
 
-      def on_sandbox(&block)
-        with_url(::DnsMadeEasy::API_BASE_URL_SANDBOX, &block)
+      def on_sandbox(&)
+        with_url(::DnsMadeEasy::API_BASE_URL_SANDBOX, &)
       end
 
-      def on_production(&block)
-        with_url(::DnsMadeEasy::API_BASE_URL_PRODUCTION, &block)
+      def on_production(&)
+        with_url(::DnsMadeEasy::API_BASE_URL_PRODUCTION, &)
       end
 
       # -----------------------------------
@@ -127,55 +127,63 @@ module DnsMadeEasy
 
       def create_a_record(domain_name, name, value, options = {})
         # TODO: match IPv4 for value
-        create_record domain_name, name, 'A', value, options
+        create_record domain_name, name, 'A', value, **options
       end
 
       def create_aaaa_record(domain_name, name, value, options = {})
         # TODO: match IPv6 for value
-        create_record domain_name, name, 'AAAA', value, options
+        create_record domain_name, name, 'AAAA', value, **options
       end
 
       def create_ptr_record(domain_name, name, value, options = {})
         # TODO: match PTR value
-        create_record domain_name, name, 'PTR', value, options
+        create_record domain_name, name, 'PTR', value, **options
       end
 
       def create_txt_record(domain_name, name, value, options = {})
         # TODO: match TXT value
-        create_record domain_name, name, 'TXT', value, options
+        create_record domain_name, name, 'TXT', value, **options
       end
 
       def create_cname_record(domain_name, name, value, options = {})
         # TODO: match CNAME value
-        create_record domain_name, name, 'CNAME', value, options
+        create_record domain_name, name, 'CNAME', value, **options
+      end
+
+      def create_aname_record(domain_name, name, value, options = {})
+        create_record domain_name, name, 'ANAME', value, **options
       end
 
       def create_ns_record(domain_name, name, value, options = {})
         # TODO: match domainname for value
-        create_record domain_name, name, 'NS', value, options
+        create_record domain_name, name, 'NS', value, **options
       end
 
       def create_spf_record(domain_name, name, value, options = {})
-        create_record domain_name, name, 'SPF', value, options
+        create_record domain_name, name, 'SPF', value, **options
       end
 
       def create_mx_record(domain_name, name, priority, value, options = {})
         options.merge!('mxLevel' => priority)
 
-        create_record domain_name, name, 'MX', value, options
+        create_record domain_name, name, 'MX', value, **options
       end
 
       def create_srv_record(domain_name, name, priority, weight, port, value, options = {})
         options.merge!('priority' => priority, 'weight' => weight, 'port' => port)
-        create_record domain_name, name, 'SRV', value, options
+        create_record domain_name, name, 'SRV', value, **options
       end
-      def create_httpred_record(domain_name, name, value, redirectType = 'STANDARD - 302', description = '', keywords = '', title = '', options = {})
-        options.merge!('redirectType' => redirectType, 'description' => description, 'keywords' => keywords, 'title' => title)
-        create_record domain_name, name, 'HTTPRED', value, options
+
+      def create_httpred_record(domain_name, name, value, redirectType = 'STANDARD - 302', description = '',
+                                keywords = '', title = '', options = {})
+        options.merge!('redirectType' => redirectType, 'description' => description, 'keywords' => keywords,
+                       'title' => title)
+        create_record domain_name, name, 'HTTPRED', value, **options
       end
 
       def update_record(domain, record_id, name, type, value, options = {})
-        body = { 'name' => name, 'type' => type, 'value' => value, 'ttl' => 3600, 'gtdLocation' => 'DEFAULT', 'id' => record_id }
+        body = { 'name' => name, 'type' => type, 'value' => value, 'ttl' => 3600, 'gtdLocation' => 'DEFAULT',
+                 'id' => record_id }
         put "/dns/managed/#{get_id_by_domain(domain)}/records/#{record_id}/", body.merge(options)
       end
 
@@ -314,12 +322,10 @@ module DnsMadeEasy
         process_rate_limits(response)
         unparsed_json = response.body.to_s.empty? ? '{}' : response.body
         Hashie::Mash.new(JSON.parse(unparsed_json))
-      rescue Net::HTTPServerException => e
-        if e.message =~ /403.*forbidden/i
-          raise ::DnsMadeEasy::AuthenticationError, e
-        else
-          raise e
-        end
+      rescue Net::HTTPClientException => e
+        raise ::DnsMadeEasy::AuthenticationError, e if e.message =~ /403.*forbidden/i
+
+        raise e
       end
 
       def process_rate_limits(response)

data/lib/dnsmadeeasy/cli/box_output.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'dnsmadeeasy/cli/message_helpers'
+
+module DnsMadeEasy
+  module CLI
+    BoxOutput = MessageHelpers
+  end
+end

data/lib/dnsmadeeasy/cli/commands/account.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require 'dnsmadeeasy/api/client'
+require 'dnsmadeeasy/cli/commands/base'
+
+module DnsMadeEasy
+  module CLI
+    # Registered dry-cli command classes.
+    module Commands
+      # Dispatches existing DNS Made Easy API operations under `dme account`.
+      class Account < Base
+        RECORD_TYPES = %w[A AAAA ANAME CNAME HTTPRED MX NS PTR SOA SPF SRV TXT].freeze
+        COMMON_OPTION_NAMES = %i[format credentials api_key api_secret record_type].freeze
+        RECORD_LIST_OPERATIONS = %w[all records_for].freeze
+        OPERATION_METADATA = {
+          'all' => {
+            usage: 'dme account all DOMAIN_NAME [--record-type=TYPE]',
+            arguments: ['DOMAIN_NAME                         # Domain name to list records for'],
+            options: ["--record-type=TYPE, -t TYPE       # Optional record type filter: (#{RECORD_TYPES.join('/')})"],
+            summary: 'List records for a managed domain'
+          },
+          'records_for' => {
+            usage: 'dme account records_for DOMAIN_NAME [--record-type=TYPE]',
+            arguments: ['DOMAIN_NAME                         # Domain name to list records for'],
+            options: ["--record-type=TYPE, -t TYPE       # Optional record type filter: (#{RECORD_TYPES.join('/')})"],
+            summary: 'List records for a managed domain'
+          },
+          'domains' => {
+            usage: 'dme account domains',
+            arguments: [],
+            options: [],
+            summary: 'List managed domains'
+          }
+        }.freeze
+
+        desc 'Execute DNS Made Easy account API operation'
+
+        option :list, aliases: ['l'], type: :boolean, default: false, desc: 'List account operations'
+        option :list_operations, type: :boolean, default: false, desc: 'List account operations'
+
+        def self.public_operation_names
+          DnsMadeEasy::Api::Client.public_operations
+        end
+
+        def self.build_operation_command(operation_name)
+          operation_class = Class.new(AccountOperation)
+          operation_class.operation_name = operation_name
+          operation_class.operation_parameters = DnsMadeEasy::Api::Client.instance_method(operation_name).parameters
+          operation_class.desc(operation_metadata(operation_name).fetch(:summary))
+          operation_class.define_operation_arguments
+          operation_class.define_record_type_option if RECORD_LIST_OPERATIONS.include?(operation_name)
+          operation_class
+        end
+
+        def self.operation_help(operation_name)
+          metadata = operation_metadata(operation_name)
+          return unknown_operation_help(operation_name) unless metadata
+
+          [
+            'Command:',
+            "  #{metadata.fetch(:usage)}",
+            '',
+            'Description:',
+            "  #{metadata.fetch(:summary)}",
+            *argument_help(metadata),
+            *option_help(metadata)
+          ].join("\n")
+        end
+
+        def self.operation_metadata(operation_name)
+          normalized_operation_name = operation_name.to_s
+          OPERATION_METADATA[normalized_operation_name] || introspected_operation_metadata(normalized_operation_name)
+        end
+
+        def self.introspected_operation_metadata(operation_name)
+          return unless public_operation_names.include?(operation_name)
+
+          method_parameters = DnsMadeEasy::Api::Client.instance_method(operation_name).parameters
+          required_arguments = method_parameters.filter_map do |parameter_type, parameter_name|
+            parameter_name.to_s.upcase if parameter_type == :req
+          end
+
+          {
+            usage: (['dme account', operation_name] + required_arguments).join(' '),
+            arguments: required_arguments.map { |argument_name| "#{argument_name.ljust(35)} # Required" },
+            options: [],
+            summary: "Execute #{operation_name}"
+          }
+        end
+
+        def self.unknown_operation_help(operation_name)
+          [
+            "Error: account operation #{operation_name.inspect} is not valid.",
+            'Hint: run `dme account --list` to see valid operations.'
+          ].join("\n")
+        end
+
+        def self.argument_help(metadata)
+          arguments = metadata.fetch(:arguments)
+          return [] if arguments.empty?
+
+          ['', 'Arguments:', *arguments.map { |argument| "  #{argument}" }]
+        end
+
+        def self.option_help(metadata)
+          options = metadata.fetch(:options)
+          return [] if options.empty?
+
+          ['', 'Options:', *options.map { |option| "  #{option}" }]
+        end
+
+        def call(args: [], list: false, list_operations: false, **)
+          reject_unknown_subcommand!(args) unless list || list_operations
+
+          print_operations
+        end
+
+        private
+
+        def reject_unknown_subcommand!(args)
+          unknown_subcommand = Array(args).first
+          return unless unknown_subcommand
+
+          warn "Error: account operation #{unknown_subcommand.inspect} is not valid."
+          warn 'Hint: run `dme account --help` to see valid operations.'
+          raise ArgumentError, "account operation #{unknown_subcommand.inspect} is not valid"
+        end
+
+        def public_operations
+          self.class.public_operation_names
+        end
+
+        def print_operations
+          public_operations.each do |operation_name|
+            metadata = self.class.operation_metadata(operation_name)
+            summary = metadata.fetch(:summary)
+            puts "#{operation_name.ljust(28)} #{summary}"
+          end
+        end
+      end
+
+      # Base command for generated account operation subcommands.
+      class AccountOperation < Base
+        class << self
+          attr_accessor :operation_name,
+                        :operation_parameters
+
+          def define_operation_arguments
+            required_operation_parameters.each do |parameter_name|
+              argument parameter_name, required: true, desc: humanize_parameter_name(parameter_name)
+            end
+          end
+
+          def define_record_type_option
+            option :record_type, aliases: ['t'], values: Account::RECORD_TYPES, required: false,
+                                 desc: 'Filter returned records by type'
+          end
+
+          def required_operation_parameters
+            operation_parameters.filter_map do |parameter_type, parameter_name|
+              parameter_name if parameter_type == :req
+            end
+          end
+
+          def optional_operation_parameters
+            operation_parameters.filter_map do |parameter_type, parameter_name|
+              parameter_name if parameter_type == :opt && parameter_name != :options
+            end
+          end
+
+          def humanize_parameter_name(parameter_name)
+            parameter_name.to_s.tr('_', ' ')
+          end
+        end
+
+        def call(format: nil, credentials: nil, api_key: nil, api_secret: nil, record_type: nil, **arguments)
+          configure_authentication(credentials: credentials, api_key: api_key, api_secret: api_secret)
+          result = DnsMadeEasy.client.public_send(self.class.operation_name, *operation_arguments(arguments))
+          result = filter_records_by_type(result, record_type) if record_type && record_list_operation?
+          print_result(result, format)
+        end
+
+        private
+
+        def operation_arguments(arguments)
+          self.class.required_operation_parameters.map { |parameter_name| arguments.fetch(parameter_name) } +
+            self.class.optional_operation_parameters.filter_map { |parameter_name| arguments[parameter_name] }
+        end
+
+        def record_list_operation?
+          Account::RECORD_LIST_OPERATIONS.include?(self.class.operation_name)
+        end
+
+        def filter_records_by_type(result, record_type)
+          filtered_record_type = record_type.upcase
+          return result unless result.respond_to?(:key?) && result.key?('data')
+
+          filtered_result = result.dup
+          filtered_result['data'] = result['data'].select { |record| record['type'] == filtered_record_type }
+          filtered_result
+        end
+
+        def print_result(result, format)
+          case result
+          when NilClass
+            puts 'No records returned.'
+          when Hashie::Mash
+            print_formatted(result.to_hash, format)
+          else
+            print_formatted(result, format)
+          end
+        end
+      end
+
+      register 'account', Account do |prefix|
+        Account.public_operation_names.each do |operation_name|
+          prefix.register operation_name, Account.build_operation_command(operation_name)
+        end
+      end
+    end
+  end
+end