empeira 0.1.0.pre.alpha.1

data/lib/empeira/completion/addons.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Completion
+    # Only local configuration and declarative manifests; never acquire or execute.
+    class Addons
+      attr_reader :file_completion, :file_prefix, :replacement
+
+      def initialize(service: Application.new.addons)
+        @service = service
+      end
+
+      def candidates(words, index, management: false)
+        prefix = words[index].to_s
+        return @service.names.grep(/^#{Regexp.escape(prefix)}/) if index.zero? || management
+
+        commands = local_commands(words.first)
+        return commands.keys.grep(/^#{Regexp.escape(prefix)}/) if index == 1
+
+        command = commands[words[1]]
+        command ? command_candidates(command, words[2...index], prefix) : []
+      rescue Empeira::Error, SystemCallError
+        []
+      end
+
+      private
+
+      def local_commands(name)
+        manifest = @service.installation(name).local&.last
+        manifest ? manifest.data.fetch('commands') : {}
+      end
+
+      def command_candidates(command, before, prefix)
+        options = command.fetch('options', {})
+        position, pending, literal = argument_position(before, options)
+        if !literal && prefix.start_with?('-') && !pending
+          return assignment(options, prefix) if prefix.include?('=')
+
+          return options.keys.grep(/^#{Regexp.escape(prefix)}/)
+        end
+        descriptor = pending || command.fetch('arguments', [])[position]
+        complete(descriptor, prefix)
+      end
+
+      def argument_position(words, options)
+        @position = 0
+        @pending = nil
+        @literal = false
+        words.each { |word| consume_word(word, options) }
+        [@position, @pending, @literal]
+      end
+
+      def consume_word(word, options)
+        if @pending
+          @pending = nil unless word == '='
+          return
+        end
+        return @position += 1 if @literal
+
+        case word
+        when '--' then @literal = true
+        when /\A-/ then @pending = option_value(word, options)
+        else @position += 1
+        end
+      end
+
+      def option_value(word, options)
+        name, value = word.split('=', 2)
+        descriptor = options[name]
+        descriptor if descriptor && descriptor['completion'] != 'none' && (value.nil? || value.empty?)
+      end
+
+      def assignment(options, prefix)
+        name, value = prefix.split('=', 2)
+        @replacement = "#{name}="
+        complete(options[name], value.to_s).map { |item| "#{@replacement}#{item}" }
+      end
+
+      def complete(descriptor, prefix)
+        return [] unless descriptor
+
+        case descriptor['completion']
+        when 'file', 'directory'
+          @file_completion = descriptor['completion']
+          @file_prefix = prefix
+          []
+        when 'enum' then descriptor.fetch('values').grep(/^#{Regexp.escape(prefix)}/)
+        else []
+        end
+      end
+    end
+  end
+end

data/lib/empeira/completion/bash.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module Empeira
+  module Completion
+    module Bash
+      module_function
+
+      # COMP_WORDS retains shell quoting, including an unfinished quoted word.
+      # Shellwords only parses text; it never evaluates substitutions or commands.
+      def path_prefix(value)
+        return value unless value.match?(/[\\'"]/)
+
+        [value, "#{value}'", "#{value}\""].each do |candidate|
+          words = Shellwords.split(candidate)
+          return words.first if words.size == 1
+        rescue ArgumentError
+          next
+        end
+        value
+      end
+
+      def generate
+        <<~'BASH'
+          # Empeira Bash completion. Load with: source <(empeira completion bash)
+          _empeira_complete() {
+            local candidate mode='' prefix='' replacement='' phase=0
+            COMPREPLY=()
+            while IFS= read -r -d '' candidate; do
+              if [[ "$candidate" == $'\x1f'file || "$candidate" == $'\x1f'directory ]]; then
+                mode="${candidate:1}"
+                phase=1
+              elif [[ $phase == 1 ]]; then
+                prefix="$candidate"
+                phase=2
+              elif [[ $phase == 2 ]]; then
+                replacement="$candidate"
+                phase=3
+              else
+                COMPREPLY+=("$candidate")
+              fi
+            done < <(printf '%s\0' "${COMP_WORDS[@]:1}" | "${COMP_WORDS[0]}" completion candidates "$COMP_CWORD" --null)
+            if [[ -n "$mode" ]]; then
+              compopt -o filenames 2>/dev/null || :
+              while IFS= read -r -d '' candidate; do COMPREPLY+=("$replacement$candidate"); done < <(
+                # Native pathname expansion with NUL framing also preserves newlines.
+                # Shell settings change only in this subshell, including on Bash 3.2.
+                shopt -s nullglob dotglob
+                for candidate in "$prefix"*; do
+                  [[ "$mode" == directory && ! -d "$candidate" ]] && continue
+                  printf '%s\0' "$candidate"
+                done
+              )
+            fi
+          }
+          complete -o filenames -F _empeira_complete empeira
+        BASH
+      end
+    end
+  end
+end

data/lib/empeira/completion/catalog.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require_relative 'addons'
+
+module Empeira
+  module Completion
+    # Shared CLI vocabulary and context parsing stay in one shell-neutral catalog.
+    # rubocop:disable-next Metrics/ClassLength
+    class Catalog
+      COMMANDS = {
+        [] => %w[help version config proxy up status down destroy node images self-update update browser completion
+                 addon addons],
+        ['addons'] => %w[help list info sync update],
+        ['update'] => ['help', *Updates::Service::TARGETS],
+        ['proxy'] => %w[help show],
+        ['config'] => %w[help show validate],
+        ['node'] => %w[help run start stop destroy list exec shell console ssh puppet logs],
+        ['completion'] => %w[help bash],
+        ['version'] => ['--verbose']
+      }.tap { |commands| Immutable.deep_freeze(commands) }
+      GLOBAL_OPTIONS = %w[--container-engine --help].freeze
+      NODE_OPTIONS = %w[--provider --os --version --memory --cpus].freeze
+      VALUE_OPTIONS = %w[--container-engine --provider --os --version --memory --cpus --user
+                         --identity --port --timeout --project-path].freeze
+
+      attr_reader :addon_completion
+
+      def candidates(words, index)
+        before = words.take(index)
+        context = command_path(before)
+        return addon_candidates(words, index, context) if addon_context?(context)
+        return [] if before.include?('--')
+
+        @before = before
+        prefix = words[index].to_s
+        assignment = assignment_prefix(prefix, before)
+        return assignment_candidates(assignment, context) if assignment
+
+        choices = values(pending_option(before), context)
+        choices ||= context_choices(context)
+        choices.grep(/^#{Regexp.escape(prefix)}/)
+      end
+
+      private
+
+      def addon_context?(context)
+        context.first == 'addon' || context == %w[addons info]
+      end
+
+      def addon_candidates(words, index, context)
+        @addon_completion = Addons.new
+        offset = words.index(context.first) + (context.first == 'addon' ? 1 : 2)
+        @addon_completion.candidates(words.drop(offset), index - offset, management: context.first == 'addons')
+      rescue Error, SystemCallError
+        []
+      end
+
+      def context_choices(context)
+        Array(node_names(context)) + COMMANDS.fetch(context, []) + options(context)
+      end
+
+      def assignment_candidates(assignment, context)
+        option, value, replacement = assignment
+        values(option, context).to_a.grep(/^#{Regexp.escape(value)}/).map { |item| "#{replacement}#{item}" }
+      end
+
+      def assignment_prefix(prefix, before)
+        if prefix.start_with?('--') && prefix.include?('=')
+          option, value = prefix.split('=', 2)
+          return [option, value, "#{option}="] if VALUE_OPTIONS.include?(option)
+        elsif prefix.start_with?('=') && VALUE_OPTIONS.include?(before.last)
+          return [before.last, prefix.delete_prefix('='), '=']
+        end
+        nil
+      end
+
+      def pending_option(before)
+        option = before.last == '=' ? before[-2] : before.last
+        option&.delete_suffix('=')
+      end
+
+      def command_path(words)
+        path = []
+        pending_value = false
+        words.each do |word|
+          if pending_value
+            pending_value = word == '='
+          elsif value_option?(word, path)
+            pending_value = true
+          elsif command_word?(word, path)
+            path << word
+          end
+        end
+        path
+      end
+
+      def value_option?(word, path)
+        option = word.delete_suffix('=')
+        VALUE_OPTIONS.include?(option) && !(option == '--version' && path.empty?)
+      end
+
+      def command_word?(word, path)
+        !word.start_with?('-') && path.size < 2
+      end
+
+      def values(option, context)
+        return Configuration::Schema::CONTAINER_ENGINES if option == '--container-engine'
+        return Empeira::Node.registry.names if option == '--provider' && context == %w[node run]
+        return node_values(option) if %w[--os --version].include?(option) && context == %w[node run]
+        return [] if VALUE_OPTIONS.include?(option)
+
+        nil
+      end
+
+      def node_names(context)
+        return unless context.size == 2 && context.first == 'node' && %w[start stop destroy exec shell console ssh
+                                                                         puppet logs].include?(context.last)
+        return recovery_node_names if context.last == 'destroy'
+
+        completion_application.nodes.names
+      rescue Error
+        []
+      end
+
+      def completion_application
+        Application.new
+      end
+
+      def recovery_node_names
+        context = Application.new(recovery: true, recovery_path: option_value('--project-path')).context
+        state = Infrastructure::Store.new(context: context, recovery: true).load
+        (state&.fetch('nodes', {})&.keys || []).select { |name| Node::Inventory.valid_name?(name) }
+      end
+
+      def option_value(option)
+        @before.each_with_index.filter_map do |word, index|
+          if word == option || word == "#{option}="
+            value = @before[index + 1]
+            value == '=' ? @before[index + 2] : value&.delete_prefix('=')
+          elsif word.start_with?("#{option}=")
+            word.split('=', 2).last
+          end
+        end.last
+      end
+
+      def node_values(option)
+        images = completion_application.context.configuration.dig('images', 'nodes')
+        return images.keys if option == '--os'
+
+        images.fetch(selected_os || completion_application.context.configuration.dig('node_defaults', 'os'), {}).keys
+      rescue Error
+        []
+      end
+
+      def selected_os
+        option_value('--os')
+      end
+
+      def options(context)
+        result = GLOBAL_OPTIONS.dup
+        result << '--version' if context.empty?
+        result.push('--user', '--identity', '--port') if context == %w[node ssh]
+        result << '--timeout' if context == %w[node exec]
+        result << '--project-path' if [['destroy'], %w[node destroy]].include?(context)
+        result.concat(NODE_OPTIONS) if context == %w[node run]
+        result
+      end
+    end
+  end
+end

data/lib/empeira/configuration/additional_services.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Configuration
+    class AdditionalServices
+      NAME = /\A[a-z][a-z0-9]*(?:-[a-z0-9]+)*\z/
+      RESERVED = %w[server puppetdb puppetdb-backend postgres dns coredns proxy gateway browser browser-ui vm-gateway
+                    bootstrap-proxy module-installer ca ssl server-data postgres-data
+                    puppetdb-data node localhost].freeze
+      FIELDS = %w[name image environment command configuration].freeze
+
+      def self.validate!(entries, path)
+        raise ConfigurationError, "#{path} must be an array" unless entries.is_a?(Array)
+
+        names = []
+        entries.each_with_index do |entry, index|
+          location = "#{path}[#{index}]"
+          validate_entry!(entry, location)
+          name = entry.fetch('name')
+          raise ConfigurationError, "#{location}.name collides with another service" if names.include?(name)
+
+          names << name
+        end
+      end
+
+      def self.validate_entry!(entry, path)
+        unless entry.is_a?(Hash) && (entry.keys - FIELDS).empty?
+          raise ConfigurationError, "#{path} must contain only name, image, environment, command and configuration"
+        end
+
+        name!(entry['name'], path)
+        image!(entry['image'], "#{path}.image")
+        optional_fields!(entry, path)
+      end
+
+      def self.optional_fields!(entry, path)
+        environment!(entry.fetch('environment', {}), "#{path}.environment")
+        command!(entry['command'], "#{path}.command") if entry.key?('command')
+        ServiceConfiguration.validate!(entry['configuration'], "#{path}.configuration") if entry.key?('configuration')
+      end
+
+      def self.name!(name, path)
+        return if name.is_a?(String) && name.length <= 63 && name.match?(NAME) && !RESERVED.include?(name)
+
+        raise ConfigurationError, "#{path}.name must be a unique lowercase DNS label, excluding built-in names"
+      end
+
+      def self.image!(image, path)
+        unless image.is_a?(Hash) && image.size == 2 && %w[repository tag].all? { |key| image.key?(key) }
+          raise ConfigurationError, "#{path} requires only repository and tag"
+        end
+
+        ImageSchema.validate!(image, path, effective: true)
+      end
+
+      def self.environment!(environment, path)
+        return if environment.is_a?(Hash) && environment.all? do |key, value|
+          key.is_a?(String) && key.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/) &&
+          value.is_a?(String) && !value.include?("\0")
+        end
+
+        raise ConfigurationError, "#{path} must map variable names to strings without null bytes"
+      end
+
+      def self.command!(command, path)
+        return if command.is_a?(Array) && !command.empty? && command.all? do |value|
+          value.is_a?(String) && !value.include?("\0")
+        end
+
+        raise ConfigurationError, "#{path} must be a nonempty argument array of strings without null bytes"
+      end
+    end
+  end
+end

data/lib/empeira/configuration/addons.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Configuration
+    module Addons
+      NAME = /\A[a-z][a-z0-9_-]*\z/
+
+      def self.validate!(entries, path = 'addons', effective: false)
+        raise ConfigurationError, "#{path} must be a mapping" unless entries.is_a?(Hash)
+
+        entries.each do |name, entry|
+          unless name.is_a?(String) && name.size <= 63 && name.match?(NAME)
+            raise ConfigurationError, "#{path} contains an invalid addon name"
+          end
+
+          entry!(entry, "#{path}.#{name}", effective: effective)
+        end
+      end
+
+      def self.entry!(entry, path, effective:)
+        unless entry.is_a?(Hash) && (entry.keys - %w[git ref config]).empty?
+          raise ConfigurationError, "#{path} may contain only git, ref and config"
+        end
+
+        require_fields!(entry, path) if effective
+        validate_fields!(entry, path)
+      end
+
+      def self.validate_fields!(entry, path)
+        validate_config!(entry['config'], "#{path}.config") if entry.key?('config')
+        if entry.key?('git') && !valid_source?(entry['git'])
+          raise ConfigurationError, "#{path}.git must be a credential-free HTTP(S) or SSH Git source"
+        end
+        return unless entry.key?('ref') && !valid_ref?(entry['ref'])
+
+        raise ConfigurationError, "#{path}.ref must be a nonempty Git reference without control characters"
+      end
+
+      def self.validate_config!(config, path)
+        raise ConfigurationError, "#{path} must be a mapping" unless config.is_a?(Hash)
+
+        config_value!(config, path)
+      end
+
+      def self.config_value!(value, path)
+        case value
+        when Hash then config_mapping!(value, path)
+        when Array then value.each_with_index { |child, index| config_value!(child, "#{path}[#{index}]") }
+        when Float
+          raise ConfigurationError, "#{path} must contain finite numbers" unless value.finite?
+        when String, Integer, TrueClass, FalseClass, NilClass then nil
+        else raise ConfigurationError, "#{path} must contain only mappings, arrays and scalar values"
+        end
+      end
+
+      def self.config_mapping!(value, path)
+        value.each do |key, child|
+          unless key.is_a?(String) && key.match?(/\A[a-z][a-z0-9_]*\z/)
+            raise ConfigurationError, "#{path} has an invalid key; use lowercase letters, digits and underscores"
+          end
+
+          config_value!(child, "#{path}.#{key}")
+        end
+      end
+
+      def self.require_fields!(entry, path)
+        %w[git ref].each do |key|
+          raise ConfigurationError, "#{path}.#{key} is required" unless entry.key?(key)
+        end
+      end
+
+      def self.valid_ref?(value)
+        value.is_a?(String) && !value.strip.empty? && !value.start_with?('-') && !value.match?(/[\p{Cc}\p{Cf}]/)
+      end
+
+      def self.valid_source?(value)
+        return false unless Modules::HostGit.valid_remote?(value)
+        return true unless value.include?('://')
+
+        uri = URI.parse(value)
+        uri.query.nil? && uri.fragment.nil?
+      end
+    end
+  end
+end

data/lib/empeira/configuration/agent_schema.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Empeira
+  module Configuration
+    # Fragment validation allows partial OS overrides; effective validation checks the resolved source.
+    # rubocop:disable-next Metrics/ModuleLength -- Keep fragment and effective validation of this source contract together.
+    module AgentSchema
+      extend AgentValues
+
+      SOURCE_VALIDATORS = { 'url' => :template_url!, 'sha256' => :digest!, 'suffix' => :suffix!,
+                            'suite' => :token!, 'component' => :token!, 'key' => :artifact!,
+                            'release' => :artifact!, 'verify_signatures' => :boolean!,
+                            'destinations' => :destinations! }.freeze
+
+      module_function
+
+      def mapping!(value, path)
+        raise ConfigurationError, "#{path} must be a mapping" unless value.is_a?(Hash)
+      end
+
+      def catalog!(value, path)
+        mapping!(value, path)
+        value.each do |key, item|
+          unless key.is_a?(String) && key.match?(/\A[a-z0-9][a-z0-9_.-]*\z/)
+            raise ConfigurationError, "#{path} has an invalid catalog key"
+          end
+
+          yield item, "#{path}.#{key}"
+        end
+      end
+
+      def validate!(data, path)
+        mapping!(data, path)
+        data.each do |key, value|
+          field = "#{path}.#{key}"
+          case key
+          when 'package' then package_token!(value, field)
+          when 'version' then token!(value, field)
+          when 'cache' then cache!(value, field)
+          when 'install' then install!(value, field)
+          else raise ConfigurationError, "#{field} is unsupported"
+          end
+        end
+      end
+
+      def cache!(data, path)
+        mapping!(data, path)
+        data.each do |key, value|
+          raise ConfigurationError, "#{path}.#{key} is unsupported" unless key == 'enabled'
+
+          boolean!(value, "#{path}.enabled")
+        end
+      end
+
+      def effective!(data)
+        required!(data, %w[package version cache install], 'agent')
+        required!(data.fetch('cache'), ['enabled'], 'agent.cache')
+        install = data.fetch('install')
+        required!(install, %w[method repositories apt dnf packages], 'agent.install')
+        install.fetch('repositories').each do |key, source|
+          required!(source, ['url'], "agent.install.repositories.#{key}")
+        end
+        %w[apt dnf].each { |manager| effective_sources!(install.fetch(manager), "agent.install.#{manager}") }
+        return unless install.fetch('method') == 'package' && install.fetch('packages').empty?
+
+        raise ConfigurationError, 'agent.install.packages must define at least one distribution and architecture'
+      end
+
+      def effective_sources!(sources, path)
+        sources.each do |key, source|
+          resolved = Merge.call(sources.fetch('default', {}), source, path: [*path.split('.'), key])
+          required!(resolved, ['url'], "#{path}.#{key}")
+          source!(resolved, "#{path}.#{key}", manager: path.split('.').last)
+        end
+      end
+
+      def install!(data, path)
+        mapping!(data, path)
+        data.each do |key, value|
+          field = "#{path}.#{key}"
+          case key
+          when 'method'
+            raise ConfigurationError, "#{field} must be repository or package" unless %w[repository
+                                                                                         package].include?(value)
+          when 'repositories' then catalog!(value, field) { |source, source_path| source!(source, source_path) }
+          when 'apt', 'dnf' then catalog!(value, field) do |source, source_path|
+            source!(source, source_path, manager: key)
+          end
+          when 'packages' then package_sources!(value, field)
+          else raise ConfigurationError, "#{field} is unsupported"
+          end
+        end
+      end
+
+      def package_sources!(data, path)
+        catalog!(data, path) do |architectures, os_path|
+          catalog!(architectures, os_path) do |artifact, artifact_path|
+            raise ConfigurationError, "#{artifact_path} has unsupported architecture" unless
+              %w[amd64 arm64].include?(artifact_path.split('.').last)
+
+            artifact!(artifact, artifact_path, package: true)
+            family = os_path.delete_prefix("#{path}.")
+            extension = family.start_with?('ubuntu', 'debian') ? '.deb' : '.rpm'
+            unless URI(artifact.fetch('url')).path.end_with?(extension)
+              raise ConfigurationError, "#{artifact_path}.url must end in #{extension}"
+            end
+          end
+        end
+      end
+
+      def artifact!(data, path, package: false)
+        mapping!(data, path)
+        allowed = package ? %w[url sha256 verify_signatures key] : %w[url sha256]
+        fields!(data, allowed, path)
+
+        required!(data, ['url'], path)
+        https_url!(data.fetch('url'), "#{path}.url")
+        digest!(data['sha256'], "#{path}.sha256") if data.key?('sha256')
+        boolean!(data['verify_signatures'], "#{path}.verify_signatures") if data.key?('verify_signatures')
+        artifact!(data['key'], "#{path}.key") if data.key?('key')
+      end
+
+      def source!(data, path, manager: nil)
+        mapping!(data, path)
+        allowed = %w[url sha256 suffix destinations verify_signatures]
+        allowed += %w[suite component release key] if manager == 'apt'
+        allowed += ['key'] if manager == 'dnf'
+        fields!(data, allowed, path)
+        data.each { |key, value| public_send(SOURCE_VALIDATORS.fetch(key), value, "#{path}.#{key}") }
+        return unless data.key?('release') && data.key?('key')
+
+        raise ConfigurationError, "#{path} cannot specify both release and key"
+      end
+
+      def destinations!(value, path)
+        raise ConfigurationError, "#{path} must contain valid proxy destination domains" unless
+          BootstrapGuests.destinations?(value)
+      end
+
+      def fields!(data, allowed, path)
+        key = (data.keys - allowed).first
+        raise ConfigurationError, "#{path}.#{key} is unsupported" if key
+      end
+
+      def template_url!(value, path)
+        raise ConfigurationError, "#{path} must be a credential-free HTTPS URL" unless value.is_a?(String)
+
+        expanded = value.gsub(/\$(?:\{([^}]+)\}|([a-zA-Z_][a-zA-Z_0-9]*))/) do
+          name = Regexp.last_match(1) || Regexp.last_match(2)
+          raise ConfigurationError, "#{path} has unknown placeholder #{name}" unless %w[suite releasever
+                                                                                        basearch].include?(name)
+
+          'target'
+        end
+        raise ConfigurationError, "#{path} has an invalid placeholder" if expanded.include?('$')
+
+        https_url!(expanded, path)
+      end
+    end
+  end
+end