empeira 0.1.0.pre.alpha.1

data/lib/empeira/agent/cache.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'digest'
+require 'fileutils'
+require 'pathname'
+require 'tmpdir'
+require 'tempfile'
+
+module Empeira
+  module Agent
+    class CacheCorruption < Error; end
+
+    class Cache
+      include CacheStorage
+
+      def initialize(root:, temporary: Dir.tmpdir)
+        @root = Pathname(root)
+        @temporary = temporary
+      end
+
+      def with_artifact(request, enabled:, acquire:, pin: nil, &use)
+        return temporary(request, pin, acquire, &use) unless enabled
+
+        prepare
+        key = fingerprint(request)
+        lock(key) do
+          artifact = load(key, request, pin) || acquire_cached(key, request, pin, acquire)
+          use.call(artifact)
+        end
+      rescue SystemCallError, IOError
+        raise Error, 'Cannot read or write the private agent cache; check ownership and permissions', cause: nil
+      end
+
+      def self.fingerprint(value)
+        Digest::SHA256.hexdigest(JSON.generate(canonical(value)))
+      end
+
+      def self.canonical(value)
+        return value.sort.to_h.transform_values { |child| canonical(child) } if value.is_a?(Hash)
+        return value.map { |child| canonical(child) } if value.is_a?(Array)
+
+        value
+      end
+
+      private
+
+      def fingerprint(value)
+        self.class.fingerprint(value)
+      end
+
+      def temporary(request, pin, acquire)
+        Dir.mktmpdir('empeira-agent-', @temporary) do |directory|
+          artifact = acquire.call(directory)
+          validate!(artifact, request, pin)
+          yield artifact
+        end
+      end
+
+      def acquire_cached(key, request, pin, acquire)
+        Dir.mktmpdir('.download-', @root.join('entries')) do |directory|
+          artifact = acquire.call(directory)
+          validate!(artifact, request, pin)
+          publish(key, artifact, request)
+        end
+      end
+
+      def load(key, request, pin)
+        reference = @root.join('refs', "#{key}.json")
+        return unless reference.exist? || reference.symlink?
+
+        owned!(reference)
+        artifact = read_artifact(reference, request)
+        validate!(artifact, request, pin)
+        artifact
+      rescue JSON::ParserError, KeyError, Errno::ENOENT, CacheCorruption
+        reference.delete if reference.exist?
+        nil
+      end
+
+      def read_artifact(reference, request)
+        entry = read_entry(reference)
+        directory = @root.join('entries', entry)
+        owned!(directory, directory: true)
+        metadata = directory.join('metadata.json')
+        owned!(metadata)
+        path = directory.join("package.#{request.fetch('format')}")
+        owned!(path)
+        Artifact.new(path: path, metadata: JSON.parse(metadata.read))
+      end
+
+      def read_entry(reference)
+        data = JSON.parse(reference.read)
+        raise CacheCorruption, 'Invalid agent cache reference' unless data.is_a?(Hash)
+
+        entry = data.fetch('entry')
+        unless entry.is_a?(String) && entry.match?(/\A[a-f0-9]{64}\z/)
+          raise CacheCorruption,
+                'Invalid agent cache reference'
+        end
+
+        entry
+      end
+
+      def validate!(artifact, request, pin)
+        metadata = artifact.metadata
+        valid = artifact.valid_identity?(request) && valid_file?(artifact, request.fetch('format'))
+        valid &&= metadata['sha256'] == pin if pin
+        raise CacheCorruption, 'Agent cache artifact or package identity is damaged' unless valid
+      end
+
+      def valid_file?(artifact, format)
+        path = artifact.path
+        return false unless path.file? && path.size.positive? && path.size == artifact.metadata['size']
+        return false unless Digest::SHA256.file(path).hexdigest == artifact.metadata['sha256']
+
+        magic = File.binread(path, 8)
+        format == 'deb' ? magic == "!<arch>\n" : magic.start_with?("\xed\xab\xee\xdb".b)
+      end
+    end
+  end
+end

data/lib/empeira/agent/cache_storage.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Agent
+    # Filesystem ownership, stable locks and atomic publication for the package cache.
+    module CacheStorage
+      private
+
+      def prepare
+        FileUtils.mkdir_p(@root.dirname, mode: 0o700)
+        [@root, @root.join('entries'), @root.join('refs'), @root.join('locks')].each do |path|
+          begin
+            Dir.mkdir(path, 0o700)
+          rescue Errno::EEXIST
+            # Concurrent creation is allowed only after ownership verification.
+          end
+          owned!(path, directory: true)
+        end
+      end
+
+      def owned!(path, directory: false)
+        stat = path.lstat
+        valid = stat.uid == Process.uid && !stat.symlink? && stat.mode.nobits?(0o077)
+        valid &&= directory ? stat.directory? : stat.file? && stat.nlink == 1
+        raise Error, 'Agent cache contains an unsafe or foreign entry; refusing access' unless valid
+      end
+
+      def lock(key)
+        path = @root.join('locks', key)
+        File.open(path, File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |file|
+          owned!(path)
+          file.flock(File::LOCK_EX)
+          yield
+        ensure
+          file.flock(File::LOCK_UN)
+        end
+      end
+
+      def publish(key, artifact, request)
+        entry = fingerprint(request.merge('native_version' => artifact.metadata.fetch('version')))
+        metadata = artifact.metadata.merge('request' => request)
+        final = commit_entry(entry, artifact, metadata, request)
+        write_reference(key, entry)
+        Artifact.new(path: final.join("package.#{request.fetch('format')}"), metadata: metadata)
+      end
+
+      def commit_entry(entry, artifact, metadata, request)
+        staging = stage_entry(artifact, metadata, request)
+        final = @root.join('entries', entry)
+        remove_owned_entry(final) if final.exist?
+        File.rename(staging, final)
+        final
+      end
+
+      def stage_entry(artifact, metadata, request)
+        staging = Pathname(File.dirname(artifact.path)).join('entry')
+        Dir.mkdir(staging, 0o700)
+        File.rename(artifact.path, staging.join("package.#{request.fetch('format')}"))
+        File.write(staging.join('metadata.json'), JSON.generate(metadata), perm: 0o600)
+        staging.children.each { |path| File.open(path, 'r+', &:fsync) }
+        staging
+      end
+
+      def remove_owned_entry(directory)
+        owned!(directory, directory: true)
+        directory.children.each { |child| owned!(child) }
+        FileUtils.remove_entry(directory)
+      end
+
+      def write_reference(key, entry)
+        reference = @root.join('refs', "#{key}.json")
+        Tempfile.create(['.ref-', '.json'], reference.dirname) do |file|
+          file.chmod(0o600)
+          file.write(JSON.generate('entry' => entry))
+          file.flush
+          file.fsync
+          File.rename(file.path, reference)
+        end
+      end
+    end
+  end
+end

data/lib/empeira/agent/download.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'openssl'
+require 'digest'
+require 'timeout'
+
+module Empeira
+  module Agent
+    # Host HTTPS transport with bounded diagnostics and acquisition-scoped authentication.
+    class Download
+      HTTP_OPTIONS = { use_ssl: true, verify_mode: OpenSSL::SSL::VERIFY_PEER,
+                       open_timeout: 10, read_timeout: 30, write_timeout: 30 }.freeze
+      FAILURE_HINTS = { '403' => 'access denied', '407' => 'Host proxy authentication failed',
+                        '404' => 'artifact unavailable' }.freeze
+      def initialize(authentication:)
+        @authentication = authentication
+      end
+
+      def fetch(url, path, sha256: nil, operation: 'Download agent package')
+        @authentication.attempt do
+          File.open(path, 'wb', 0o600) do |file|
+            request(url, operation) do |response|
+              write_response(file, response)
+            end
+            file.flush
+            file.fsync
+          end
+        end
+        raise Error, 'Agent artifact download is empty' if File.empty?(path)
+        raise Error, 'Agent artifact checksum mismatch' if sha256 && Digest::SHA256.file(path).hexdigest != sha256
+      rescue StandardError, Interrupt
+        FileUtils.rm_f(path)
+        raise
+      end
+
+      private
+
+      def write_response(file, response)
+        response.read_body { |part| file.write(part) }
+        length = response['Content-Length']
+        raise Error, 'Agent artifact download is incomplete' if length && file.size != Integer(length)
+      end
+
+      def request(url, operation)
+        received = nil
+        uri = URI(url)
+        Configuration::AgentSchema.https_url!(url, 'agent artifact URL')
+        Timeout.timeout(180) do
+          Net::HTTP.start(uri.host, uri.port, **HTTP_OPTIONS) do |http|
+            http.request(http_request(uri)) do |response|
+              received = response
+              yield validate_response!(response, url, operation)
+            end
+          end
+        end
+      rescue SocketError, OpenSSL::SSL::SSLError, IOError, SystemCallError, Timeout::Error, Net::ProtocolError => e
+        detail = Execution::Diagnostics.transport(operation: operation, url: url, error: e,
+                                                  response: received, secrets: @authentication.credentials || [])
+        raise Error, "Agent HTTPS download failed\n#{detail}", cause: nil
+      end
+
+      def http_request(uri)
+        request = Net::HTTP::Get.new(uri.request_uri)
+        request['Accept-Encoding'] = 'identity'
+        credentials = @authentication.credentials(uri.to_s)
+        request.basic_auth(*credentials) if credentials
+        request
+      end
+
+      def validate_response!(response, url, operation)
+        return response if response.code == '200'
+
+        detail = Execution::Diagnostics.http_response(response, operation: operation, url: url,
+                                                                secrets: @authentication.credentials || [])
+        raise AuthenticationRequired.new(detail, url: url) if response.code == '401'
+
+        fallback = response.code.start_with?('3') ? 'redirects are not followed' : 'HTTP error response'
+        hint = FAILURE_HINTS.fetch(response.code, fallback)
+        raise Error, "Agent HTTPS request failed: #{hint}\n#{detail}", cause: nil
+      end
+    end
+  end
+end

data/lib/empeira/agent/native_commands.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Agent
+    # Shared helper execution, scoped authentication, artifact delivery and release ownership.
+    module NativeCommands
+      private
+
+      def download_artifact(artifact, filename)
+        path = File.join(@directory, filename)
+        operation = filename == 'signing-key' ? 'Download agent signing key' : 'Download agent release package'
+        @download.fetch(artifact.fetch('url'), path, sha256: artifact['sha256'], operation: operation)
+        path
+      end
+
+      def install_auth
+        credentials = @authentication.credentials
+        return unless credentials
+
+        uri = URI(@source.fetch('url'))
+        endpoint = "https://#{uri.host}#{":#{uri.port}" unless uri.port == 443}"
+        # APT's netrc parser treats quotes and backslashes as literal credential bytes.
+        content = "machine #{endpoint}\nlogin #{credentials.first}\npassword #{credentials.last}\n"
+        copy_text(content, self.class::AUTH_PATH, mode: '0600')
+      end
+
+      def native!(arguments, operation)
+        @authentication.attempt do
+          install_auth
+          execute!(arguments, operation)
+        end
+      end
+
+      def execute!(arguments, operation)
+        result = @execute.call(arguments)
+        return result if result.success?
+
+        text = @authentication.redact("#{result.stderr}\n#{result.stdout}")
+        diagnostic = Execution::Diagnostics.native(result.with(stderr: text, stdout: ''),
+                                                   operation: "Agent #{operation}", tool: arguments.first)
+        case text
+        when /407\s+Proxy Authentication Required|(?:HTTP|Status code|HTTP code)\s*:?\s*407\b/i
+          raise Error, "Host helper proxy authentication failed\n#{diagnostic}", cause: nil
+        when /401\s+Unauthorized|(?:HTTP|Status code|HTTP code)\s*:?\s*401\b/i
+          raise Agent::AuthenticationRequired, diagnostic, cause: nil
+        when /403\s+Forbidden|(?:HTTP|Status code|HTTP code)\s*:?\s*403\b/i
+          raise Error, "Agent repository access denied\n#{diagnostic}", cause: nil
+        end
+        raise Error, "Agent #{operation} failed\n#{diagnostic}", cause: nil
+      end
+
+      def copy_text(content, destination, mode:)
+        Node::PackageProxy.copy_text(@copy, content, destination, mode: mode)
+      end
+
+      def require_absent_release!(name)
+        Configuration::AgentSchema.package_token!(name, 'Agent release package name')
+        return unless installed_release_packages.include?(name)
+
+        raise Error, 'Agent release package already exists in the helper; refusing to replace or remove it'
+      end
+
+      def installed_release_packages
+        execute!(release_inventory_arguments, 'release-package ownership verification').stdout.lines.map(&:strip)
+      end
+
+      def release_inventory_arguments
+        ['dpkg-query', '-W', '-f=${Package}\n']
+      end
+
+      def release_removal_arguments
+        ['dpkg', '--purge', '--', @release_package]
+      end
+
+      def remove_release_package
+        return unless installed_release_packages.include?(@release_package)
+
+        execute!(release_removal_arguments, 'release package cleanup')
+        raise Error, 'Cannot verify agent helper release package cleanup' if
+          installed_release_packages.include?(@release_package)
+      end
+    end
+  end
+end

data/lib/empeira/agent/release_sources.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Agent
+    # Apply the selected-source policy to native source files supplied by a release package.
+    module ReleaseSources
+      DNF_SCOPED_OPTIONS = %w[gpgcheck sslverify skip_if_unavailable includepkgs username password
+                              mirrorlist metalink].freeze
+
+      module_function
+
+      def apt(content, format:, source:)
+        urls = content.scan(%r{[a-z][a-z0-9+.-]*://[^\s]+}i)
+        raise Error, 'Agent release package must provide HTTPS APT sources' if urls.empty?
+
+        urls.each { |url| Configuration::AgentSchema.https_url!(url, 'agent release source URL') }
+        trusted = source['verify_signatures'] == false
+        format == '.sources' ? policy_deb822(content, trusted) : policy_list(content, trusted)
+      end
+
+      def policy_deb822(content, trusted)
+        content.split(/\n\s*\n/).map do |stanza|
+          safe = stanza.gsub(/^(?:Trusted|Allow-Insecure|Allow-Weak|Allow-Downgrade-To-Insecure):.*\n?/i, '').rstrip
+          "#{safe}\n#{"Trusted: yes\n" if trusted}"
+        end.join("\n")
+      end
+
+      def policy_list(content, trusted)
+        content.gsub(/^(\s*deb(?:-src)?\s+)(?:\[([^\]]*)\]\s+)?/) do
+          prefix = Regexp.last_match(1)
+          options = Regexp.last_match(2).to_s.gsub(/\b(?:trusted|allow-[a-z-]+)=\S+/, '').strip
+          options = [options, ('trusted=yes' if trusted)].compact.reject(&:empty?).join(' ')
+          "#{prefix}#{"[#{options}] " unless options.empty?}"
+        end
+      end
+
+      def dnf(content, target:, source:, package:)
+        sections = content.split(/(?=^\[)/)
+        sections.map do |section|
+          section.start_with?('[') ? dnf_section(section, target, source, package) : section
+        end.join
+      end
+
+      def scoped_dnf(section, source)
+        section = section.gsub(/^\s*(?:#{DNF_SCOPED_OPTIONS.join('|')})\s*=.*\n?/, '')
+        if source['verify_signatures'] == false
+          section = section.gsub(/^\s*repo_gpgcheck\s*=.*\n?/, '')
+          section = "#{section.rstrip}\nrepo_gpgcheck=0\n"
+        end
+        section
+      end
+
+      def dnf_section(section, target, source, package)
+        urls = section.scan(/^\s*baseurl\s*=\s*(.+)$/).flatten.flat_map(&:split)
+        raise Error, 'Agent release package must provide explicit HTTPS DNF base URLs' if urls.empty?
+
+        urls.each { |url| Configuration::AgentSchema.https_url!(target.expand(url), 'agent release source URL') }
+        section = scoped_dnf(section, source)
+        "#{section.rstrip}\ngpgcheck=#{source['verify_signatures'] == false ? 0 : 1}\n" \
+          "sslverify=1\nskip_if_unavailable=0\nincludepkgs=#{package}\n"
+      end
+    end
+  end
+end

data/lib/empeira/agent/target.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Agent
+    class Target < Data.define(:os, :release, :architecture)
+      SUITES = { '22.04' => 'jammy', '24.04' => 'noble' }.freeze
+      ARCHITECTURES = { 'amd64' => 'x86_64', 'arm64' => 'aarch64' }.freeze
+
+      def family
+        Node::PackageBootstrap::FAMILIES.fetch(os)
+      end
+
+      def format
+        family == 'debian' ? 'deb' : 'rpm'
+      end
+
+      def native_architecture
+        family == 'debian' ? architecture : ARCHITECTURES.fetch(architecture)
+      end
+
+      def key
+        family == 'debian' ? "#{os}#{release}" : "el#{release}"
+      end
+
+      def expand(value)
+        values = { 'suite' => SUITES[release], 'releasever' => release, 'basearch' => native_architecture }
+        value.gsub(/\$(?:\{([^}]+)\}|([a-zA-Z_][a-zA-Z_0-9]*))/) do
+          values.fetch(Regexp.last_match(1) || Regexp.last_match(2)) do
+            raise ConfigurationError, 'Unknown agent repository placeholder'
+          end || raise(ConfigurationError, 'Agent repository suite is unavailable for this target')
+        end
+      end
+
+      def source(install)
+        return package_source(install) if install.fetch('method') == 'package'
+
+        manager = family == 'debian' ? 'apt' : 'dnf'
+        sources = install.fetch(manager)
+        return install.fetch('repositories').fetch(key) unless configured?(sources)
+
+        resolved = Configuration::Merge.call(sources.fetch('default', {}), sources.fetch(key, {}),
+                                             path: ['agent', 'install', manager, key])
+        expand_source(resolved)
+      end
+
+      private
+
+      def package_source(install)
+        install.fetch('packages').fetch(key).fetch(architecture)
+      end
+
+      def configured?(sources)
+        sources.key?('default') || sources.key?(key)
+      end
+
+      def expand_source(source)
+        resolved = source.transform_values { |value| value.is_a?(String) ? expand(value) : value }
+        if family == 'debian'
+          resolved['suite'] ||= SUITES.fetch(release)
+          resolved['component'] ||= 'main'
+        end
+        resolved
+      end
+    end
+  end
+end

data/lib/empeira/agent/versions.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Agent
+    # Exact identity matching only; ordering remains the native package manager's responsibility.
+    module Versions
+      module_function
+
+      def match?(native, requested, suffix: nil)
+        return native == "#{requested}#{suffix}" if suffix
+        return true if native == requested
+        return false if requested.include?('-') || requested.include?(':')
+
+        native.split(':').last.split('-', 2).first == requested
+      end
+
+      def select(candidates, requested, suffix: nil)
+        matches = candidates.select { |candidate| match?(candidate.fetch('version'), requested, suffix: suffix) }.uniq
+        raise Error, 'Requested agent version is unavailable in the selected source' if matches.empty?
+        if matches.size > 1
+          raise Error,
+                'Requested agent version is ambiguous; specify the full native version or suffix'
+        end
+
+        matches.first
+      end
+    end
+  end
+end

data/lib/empeira/application.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Empeira
+  class Application
+    Context = Data.define(:project, :workspace, :configuration, :platform, :locations) do
+      def container_engine
+        configuration.fetch('runtime').fetch('container_engine')
+      end
+    end
+
+    attr_reader :context, :runner
+
+    # Dependencies are explicit at this single composition boundary.
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(project_path: Dir.pwd, overrides: {}, platform: Platform::Facts.new, runner: nil,
+                   factories: {}, locations: nil, build_info: BuildInfo.load, progress: Progress.new,
+                   recovery: false, recovery_path: nil)
+      @runner = runner || Execution::Runner.new(platform: platform)
+      locations ||= Platform::Locations.new(facts: platform)
+      if recovery
+        @context = recovery_context(project_path, recovery_path, platform, locations)
+      else
+        raise ConfigurationError, 'Explicit recovery project paths are only available for destroy' if recovery_path
+
+        project = ProjectRoot.resolve(project_path, runner: @runner)
+        @context = build_context(project:, locations:, platform:, overrides:)
+      end
+      @progress = progress
+      @build_info = build_info
+      @factories = { providers: Node.registry, runtimes: Runtime.registry,
+                     engines: VM.registry }.merge(factories).freeze
+    end
+
+    # rubocop:enable Metrics/ParameterLists
+
+    def infrastructure
+      Infrastructure::Service.new(context: context, runner: runner, runtimes: @factories.fetch(:runtimes),
+                                  build_info: @build_info, progress: @progress)
+    end
+
+    def updates
+      Updates::Service.new(context: context, runner: runner, runtimes: @factories.fetch(:runtimes),
+                           build_info: @build_info, progress: @progress)
+    end
+
+    def addons
+      Addons::Service.new(context: context, runner: runner)
+    end
+
+    def nodes
+      Node::Service.new(context: context, runner: runner, **@factories, build_info: @build_info, progress: @progress,
+                        ssh_preferences: @ssh_preferences)
+    end
+
+    def run_node(hostname:, provider:)
+      request = Node::RunRequest.from_config(hostname: hostname, provider: provider, config: context.configuration)
+      nodes.run(request)
+    end
+
+    private
+
+    # rubocop:disable-next Metrics/AbcSize -- Resolve the saved owner independently of live project configuration.
+    def recovery_context(project_path, recovery_path, platform, locations)
+      project = ProjectRoot.resolve(project_path, runner: @runner, recovery: true) unless recovery_path
+      workspace = recovery_path ? Workspace.recover(recovery_path) : Workspace.new(path: project)
+      configuration = Configuration::Document.new.read(Configuration::Loader::DEFAULTS)
+      Configuration::Schema.new.validate_effective!(configuration)
+      context = Context.new(project: project, workspace: workspace, configuration: configuration,
+                            platform: platform, locations: locations)
+      state = Infrastructure::Store.new(context: context, recovery: true).load
+      configuration.fetch('runtime')['container_engine'] = state.fetch('runtime') if state
+      @ssh_preferences = {}.freeze
+      Context.new(project: project, workspace: workspace, configuration: Immutable.deep_freeze(configuration),
+                  platform: platform, locations: locations)
+    end
+
+    def build_context(project:, locations:, platform:, overrides:)
+      loader = Configuration::Loader.new(project_path: project, locations: locations)
+      configuration = loader.load(overrides: overrides)
+      @ssh_preferences = loader.ssh_preferences
+      workspace = Workspace.new(path: project)
+      Context.new(project: project, workspace: workspace, configuration: Immutable.deep_freeze(configuration),
+                  platform: platform, locations: locations)
+    end
+  end
+end

data/lib/empeira/build.json

@@ -0,0 +1,5 @@
+{
+  "version": "0.1.0-alpha.1",
+  "revision": "7cd2d71ea0b7cfa7008f8faf18e975499c5af9c0",
+  "build_time": "2026-10-14T09:19:05Z"
+}

data/lib/empeira/build_info.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'version_requirement'
+
+module Empeira
+  class BuildInfo
+    METADATA_PATH = File.expand_path('build.json', __dir__).freeze
+    attr_reader :version, :revision, :build_time
+
+    def self.load(path: METADATA_PATH)
+      data = File.file?(path) ? JSON.parse(File.read(path)) : {}
+      new(**data.transform_keys(&:to_sym))
+    end
+
+    def initialize(version: 'development', revision: nil, build_time: nil)
+      @version = version.delete_prefix('v').freeze
+      @revision = revision&.dup&.freeze
+      @build_time = build_time&.dup&.freeze
+      freeze
+    end
+
+    def gem_version
+      version == 'development' ? '0.0.0.development' : version
+    end
+
+    def requirement_status(requirement)
+      parsed = VersionRequirement.parse(requirement)
+      return 'not required' unless parsed
+      return 'unverifiable (development build)' if version == 'development'
+
+      parsed.satisfied_by?(Gem::Version.new(version)) ? 'satisfied' : 'incompatible'
+    end
+
+    def require_compatible!(requirement)
+      return if ['not required', 'satisfied'].include?(requirement_status(requirement))
+
+      raise Error, "Empeira version requirement is not satisfied.\nRequired: #{requirement}\nInstalled: #{version}\n" \
+                   "Update Empeira before modifying this project.\nRun: empeira self-update"
+    end
+
+    def to_h
+      { version: version, revision: revision, build_time: build_time }
+    end
+  end
+end