empeira 0.1.0.pre.alpha.1

data/lib/empeira/cli/addons.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Empeira
+  module CLI
+    class Addons < Base
+      desc 'list', 'List configured addons and local installation status'
+      def list
+        service = application.addons
+        service.names.each do |name|
+          say "#{name}: #{local_status(service.installation(name))}"
+        end
+      end
+
+      desc 'info NAME', 'Show source, reference, commit, path and manifest'
+      def info(name)
+        entry = application.addons.installation(name)
+        say "Addon: #{name}\nGit: #{entry.source}\nRef: #{entry.ref}"
+        local = entry.local
+        return say('Status: missing; run empeira addons sync') unless local
+
+        commit, path, manifest = local
+        say "Commit: #{commit}\nPath: #{path}\n#{YAML.dump(manifest.data)}"
+      end
+
+      %w[sync update].each do |operation|
+        desc operation, 'Synchronize configured Git addons without starting infrastructure'
+        define_method(operation) do
+          application.addons.synchronize
+          say 'Configured addons synchronized.'
+        end
+      end
+
+      no_commands do
+        def local_status(entry)
+          local = entry.local
+          local ? "installed (#{entry.ref}, #{local.first})" : "missing (#{entry.ref})"
+        rescue Empeira::Addons::Error => e
+          "invalid (#{e.message})"
+        end
+      end
+    end
+  end
+end

data/lib/empeira/cli/base.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'thor'
+require_relative 'progress'
+
+module Empeira
+  module CLI
+    class Base < Thor
+      check_unknown_options!
+      class_option :container_engine, type: :string, enum: Configuration::Schema::CONTAINER_ENGINES,
+                                      desc: 'Override runtime.container_engine'
+
+      def self.exit_on_failure?
+        true
+      end
+
+      # Extract only the explicit guest argv before Thor reparses a nested subcommand.
+      def self.start(given_args = ARGV, config = {})
+        boundary = given_args.index('--')
+        prefix = boundary && given_args.take(boundary)
+        if prefix && (prefix.each_cons(2).include?(%w[node exec]) ||
+                       (name == 'Empeira::CLI::Node' && prefix.first == 'exec'))
+          config = config.merge(guest_arguments: given_args.drop(boundary + 1))
+          given_args = prefix
+        end
+        super
+      end
+
+      def initialize(args = [], local_options = {}, config = {})
+        @guest_arguments = config[:guest_arguments]
+        @addon_arguments = config[:addon_arguments]
+        super
+      end
+
+      # Thor groups presentation helpers outside its command DSL.
+      # rubocop:disable-next Metrics/BlockLength
+      no_commands do
+        def application(node: false, progress: Empeira::Progress.new, recovery: false)
+          overrides = runtime_overrides
+          overrides = Configuration::Merge.call(overrides, node_overrides) if node
+          Application.new(project_path: Dir.pwd, overrides: overrides, progress: progress, recovery: recovery,
+                          recovery_path: recovery ? options[:project_path] : nil)
+        end
+
+        def progressing(message, node: false, recovery: false)
+          renderer = ProgressRenderer.new
+          progress = Empeira::Progress.new(listener: renderer)
+          renderer.during do
+            progress.run(message) { yield application(node: node, progress: progress, recovery: recovery) }
+          end
+        end
+
+        def runtime_overrides
+          return {} unless options[:container_engine]
+
+          { 'runtime' => { 'container_engine' => options[:container_engine] } }
+        end
+
+        def node_overrides
+          values = options.slice('os', 'version', 'memory', 'cpus').to_h
+          %w[memory cpus].each { |key| values[key] = parse_integer(key, values[key]) if values.key?(key) }
+          { 'node_defaults' => values }
+        end
+
+        def parse_integer(key, value)
+          Integer(value, 10)
+        rescue ArgumentError
+          raise ConfigurationError, "node_defaults.#{key} must be a positive integer"
+        end
+      end
+    end
+  end
+end

data/lib/empeira/cli/completion.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative '../completion/catalog'
+require_relative '../completion/bash'
+
+module Empeira
+  module CLI
+    class Completion < Base
+      desc 'bash', 'Print Bash completion for sourcing in your shell'
+      def bash
+        say Empeira::Completion::Bash.generate
+      end
+
+      desc 'candidates INDEX', 'Return completion candidates', hide: true
+      option :null, type: :boolean, default: false, hide: true
+      def candidates(index)
+        words = $stdin.read.split("\0", -1)
+        words.pop
+        cursor = Integer(index, 10) - 1
+        return if cursor.negative?
+
+        emit_candidates(words, cursor)
+      rescue ArgumentError
+        raise Error, 'Completion index must be an integer'
+      end
+
+      no_commands do
+        def emit_candidates(words, cursor)
+          catalog = Empeira::Completion::Catalog.new
+          values = catalog.candidates(words, cursor)
+          addon = catalog.addon_completion
+          if addon&.file_completion
+            values += ["\x1f#{addon.file_completion}", Empeira::Completion::Bash.path_prefix(addon.file_prefix),
+                       addon.replacement.to_s]
+          end
+          separator = options[:null] ? "\0" : "\n"
+          values.each { |value| $stdout.write("#{value}#{separator}") }
+        end
+      end
+    end
+  end
+end

data/lib/empeira/cli/config.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Empeira
+  module CLI
+    class Config < Base
+      desc 'show', 'Display the effective configuration'
+      def show
+        app = application
+        data = Configuration::Display.redact(app.context.configuration)
+        mounts = ControlPlane::Plan.new(context: app.context).hiera.entries
+        data['effective_hiera_mounts'] = mounts unless mounts.empty?
+        say YAML.dump(data)
+      end
+
+      desc 'validate', 'Validate the effective configuration'
+      def validate
+        application.context.configuration
+        say 'Configuration is valid.'
+      end
+    end
+  end
+end

data/lib/empeira/cli/main.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'config'
+require_relative 'node'
+require_relative 'proxy'
+require_relative 'completion'
+require_relative 'update'
+require_relative 'addons'
+
+module Empeira
+  module CLI
+    class Main < Base
+      # Strip the opaque addon argv before Thor can interpret --help, --version,
+      # assignments, or a literal -- as Core options.
+      def self.start(given_args = ARGV, config = {})
+        index = addon_index(given_args)
+        if index && given_args[index + 1]&.match?(Configuration::Addons::NAME)
+          config = config.merge(addon_arguments: given_args.drop(index + 2))
+          given_args = [*given_args[index, 2], *given_args.take(index)]
+        end
+        super
+      end
+
+      def self.addon_index(arguments)
+        index = 0
+        index += arguments[index].include?('=') ? 1 : 2 while arguments[index]&.start_with?('--container-engine')
+        index if arguments[index] == 'addon'
+      end
+
+      desc 'addon NAME [ARGUMENTS...]', 'Run a configured standalone addon'
+      def addon(name)
+        application.addons.execute(name, @addon_arguments || [])
+      end
+
+      desc 'addons SUBCOMMAND', 'Manage configured Git addons'
+      subcommand 'addons', Addons
+
+      desc 'version', 'Show build version'
+      option :verbose, type: :boolean, desc: 'Include revision and build time'
+      map '--version' => :version
+      def version
+        info = BuildInfo.load
+        say(options[:verbose] ? JSON.pretty_generate(info.to_h) : "Empeira #{info.version}")
+      end
+
+      desc 'config SUBCOMMAND', 'Show or validate project configuration'
+      subcommand 'config', Config
+      desc 'proxy SUBCOMMAND', 'Explain hostname-specific proxy policy'
+      subcommand 'proxy', Proxy
+      desc 'node SUBCOMMAND', 'Container and VM test-node lifecycle'
+      subcommand 'node', Node
+      desc 'completion SUBCOMMAND', 'Shell completion'
+      subcommand 'completion', Completion
+
+      desc 'status', 'Inspect workspace infrastructure without changing state'
+      def status
+        application.infrastructure.status.each { |key, value| say "#{key}: #{value}" }
+      end
+
+      desc 'up', 'Ensure isolated workspace infrastructure'
+      def up
+        addon_error = nil
+        result = progressing('Preparing workspace...') do |app|
+          ready = app.infrastructure.up
+          begin
+            app.addons.synchronize(missing_only: true)
+          rescue Empeira::Addons::Error => e
+            addon_error = e
+          end
+          ready
+        end
+        say(result.changed ? 'Workspace control plane is ready.' : 'Workspace control plane is already ready.')
+        raise addon_error if addon_error
+      end
+
+      desc 'browser', 'Start the disposable internal browser and print its loopback HTTPS URL'
+      def browser
+        url = progressing('Preparing internal browser...') { |app| app.infrastructure.browser }
+        say url
+      end
+
+      desc 'down', 'Remove owned workspace infrastructure'
+      def down
+        result = progressing('Stopping workspace...') { |app| app.infrastructure.down }
+        action = result.changed ? 'removed' : 'already absent'
+        say "Workspace services #{action}; persistent data retained."
+      end
+
+      desc 'destroy', 'Permanently remove services, CA and database volumes'
+      option :project_path, type: :string,
+                            desc: 'Former absolute Git root path for recovery without a control repository'
+      def destroy
+        progressing('Removing workspace...', recovery: true) { |app| app.infrastructure.destroy }
+        say 'Workspace infrastructure and persistent data removed.'
+      end
+
+      desc 'self-update', 'Update only Empeira (not implemented yet)'
+      def self_update
+        Updates::Service.new.self_update
+      end
+
+      desc 'update SUBCOMMAND', 'Update managed targets (not implemented yet)'
+      subcommand 'update', Update
+
+      %w[images].each do |operation|
+        desc "#{operation} [SUBCOMMAND]", 'Not implemented yet'
+        define_method(operation) do |*_arguments|
+          raise UnavailableFeature, 'This command is not implemented yet.'
+        end
+      end
+    end
+  end
+end

data/lib/empeira/cli/node.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Empeira
+  module CLI
+    class Node < Base
+      map 'run' => :run_node, 'shell' => :shell_node, 'exec' => :exec_node
+
+      desc 'exec HOSTNAME -- COMMAND [ARGUMENTS...]', 'Run a root guest command without SSH or implicit shell parsing'
+      option :timeout, type: :numeric, desc: 'Guest command timeout in seconds (default: unlimited)'
+      def exec_node(hostname, *_arguments)
+        arguments = @guest_arguments || []
+        Empeira::Node::DiagnosticCommand.validate!(arguments, options[:timeout])
+        result = application.nodes.exec(name: hostname, arguments: arguments, timeout: options[:timeout])
+        if result.timed_out
+          warn 'Guest command timed out; its process groups were stopped.'
+          raise SystemExit, 124
+        end
+        raise SystemExit, result.exit_status
+      end
+
+      desc 'run HOSTNAME', 'Create a container or VM node and run its agent'
+      option :provider, type: :string, default: 'container', enum: Empeira::Node.registry.names,
+                        desc: 'Node provider (default: container)'
+      option :os, type: :string, desc: 'Operating system'
+      option :version, type: :string, desc: 'Operating system version'
+      option :memory, type: :string, desc: 'Memory in MiB (positive integer)'
+      option :cpus, type: :string, desc: 'CPU count (positive integer)'
+      def run_node(hostname)
+        progressing('Preparing node...', node: true) do |app|
+          app.run_node(hostname: hostname, provider: options[:provider])
+        end
+      end
+
+      desc 'ssh HOSTNAME', 'Open system SSH (VM: managed identity; container: local user authentication)'
+      option :user, type: :string, desc: 'Remote login user (overrides personal SSH preferences)'
+      option :identity, type: :string, desc: 'SSH identity file (VM default: managed key)'
+      option :port, type: :string, desc: 'System SSH guest port (default: 22)'
+      def ssh(hostname)
+        result = application.nodes.ssh(name: hostname, user: options[:user], identity: options[:identity],
+                                       port: ssh_port)
+        raise SystemExit, result.exit_status unless result.success?
+      end
+
+      no_commands do
+        def ssh_port
+          return unless options[:port]
+
+          Configuration::SSHPreferences.port!(Integer(options[:port], 10))
+        rescue ArgumentError
+          raise ConfigurationError, 'SSH port must be an integer from 1 to 65535'
+        end
+      end
+
+      %w[start stop destroy shell console puppet logs].each do |operation|
+        descriptions = { 'shell' => 'Open an interactive root terminal (runtime exec or VM VirtIO PTY)',
+                         'console' => 'Attach to the private VM serial console; Ctrl+] detaches',
+                         'destroy' => 'Remove an owned node without version or guest-access requirements' }
+        desc "#{operation} HOSTNAME", descriptions.fetch(operation, "#{operation.capitalize} an existing node")
+        if operation == 'destroy'
+          option :project_path, type: :string,
+                                desc: 'Former absolute Git root path for recovery without a control repository'
+        end
+        define_method(operation == 'shell' ? 'shell_node' : operation) do |hostname|
+          if %w[shell console ssh logs].include?(operation)
+            result = application.nodes.public_send(operation, name: hostname)
+            raise SystemExit, result.exit_status if operation == 'ssh' && !result.success?
+            raise Error, "Node #{operation} failed" unless result.success?
+          else
+            progressing("#{operation.capitalize} node...", recovery: operation == 'destroy') do |app|
+              app.nodes.public_send(operation, name: hostname)
+            end
+          end
+        end
+      end
+
+      desc 'list', 'List workspace nodes and observed runtime state'
+      def list
+        rows = application.nodes.list
+        say 'HOSTNAME PROVIDER RUNTIME OS/VERSION STATE PUPPET_EXIT NETWORK'
+        rows.each do |row|
+          say [row['hostname'], row['provider'], row['runtime'], "#{row['os']}/#{row['version']}",
+               row['state'], row['last_puppet_exit'] || '-', row['network'] || '-'].join(' ')
+        end
+      end
+    end
+  end
+end

data/lib/empeira/cli/progress.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require 'io/console'
+
+module Empeira
+  module CLI
+    # The cursor stays on the second row while a workflow is active.
+    class ProgressDisplay
+      DEFAULT_COLUMNS = 80
+      MIN_BAR_COLUMNS = 4
+
+      def initialize(io:, columns: nil)
+        @io = io
+        @columns = columns
+        @drawn = false
+      end
+
+      def render(event, waiting: false)
+        return finish unless event.state == :active
+
+        available = [terminal_columns - 1, 0].max
+        message = ProgressRenderer.clean_message(event.message)
+        message += waiting == true ? ' (still working)' : " (still working #{waiting})" if waiting
+        @io.print("\r\e[1A") if @drawn
+        @io.print("\r\e[2K", progress_line(event.percent, available), "\n\r\e[2K", truncate(message, available))
+        @drawn = true
+        @io.flush
+      end
+
+      def finish
+        return unless @drawn
+
+        @io.print("\r\e[2K\e[1A\r\e[2K")
+        @io.flush
+        @drawn = false
+      end
+
+      private
+
+      def progress_line(percent, available)
+        label = format('%3d%%', percent)
+        bar_width = available - label.length - 3
+        if bar_width < MIN_BAR_COLUMNS
+          compact = "[#{percent}%]"
+          compact = "#{percent}%" if compact.length > available
+          return compact.length <= available ? compact : ''
+        end
+
+        filled = (bar_width * percent / 100.0).round
+        "[#{'█' * filled}#{'-' * (bar_width - filled)}] #{label}"
+      end
+
+      def truncate(message, available)
+        return '' if available.zero?
+        return message if message.bytesize <= available
+
+        suffix = available >= 4 ? '...' : ''
+        budget = available - suffix.length
+        result = +''
+        message.each_grapheme_cluster do |cluster|
+          break if result.bytesize + cluster.bytesize > budget
+
+          result << cluster
+        end
+        result << suffix
+      end
+
+      def terminal_columns
+        value = @columns ? @columns.call : @io.winsize.last
+        value.is_a?(Integer) && value.positive? ? value : DEFAULT_COLUMNS
+      rescue IOError, SystemCallError, NoMethodError
+        DEFAULT_COLUMNS
+      end
+    end
+
+    class ProgressRenderer
+      SPINNER = ['|', '/', '-', '\\'].freeze
+      SPINNER_INTERVAL = 0.25
+
+      def self.clean_message(message)
+        message.to_s.scrub.gsub(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/, ' ')
+      end
+
+      def initialize(io: $stderr, interactive: nil, columns: nil, heartbeat_interval: 10, clock: nil)
+        @io = io
+        active = interactive.nil? ? interactive_output? : interactive
+        @display = ProgressDisplay.new(io: io, columns: columns) if active
+        @heartbeat_interval = heartbeat_interval
+        @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+        @spinner = 0
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+      end
+
+      def call(event)
+        @mutex.synchronize do
+          @io.print("\n") if @event&.state == :suspended && event.state == :failed
+          @event = event
+          @spinner = 0
+          @next_tick = @clock.call + @heartbeat_interval
+          render_state(event)
+          @condition.signal
+        end
+      end
+
+      def during
+        @finished = false
+        heartbeat = Thread.new { heartbeat_loop }
+        yield
+      ensure
+        if heartbeat
+          @mutex.synchronize do
+            @finished = true
+            @condition.signal
+          end
+          heartbeat.join
+        end
+        @mutex.synchronize { @display&.finish }
+      end
+
+      private
+
+      def render_state(event)
+        if event.state == :warning
+          @display&.finish
+          @io.puts(self.class.clean_message(event.message))
+          @io.flush
+        elsif %i[suspended resumed].include?(event.state)
+          @display&.finish
+          @io.print("\n") if event.state == :resumed
+        else
+          render(event)
+        end
+      end
+
+      def interactive_output?
+        Execution::Terminal.interactive?(error: @io)
+      end
+
+      def heartbeat_loop
+        @mutex.synchronize do
+          until @finished
+            tick
+            delay = @event&.state == :active ? [@next_tick - @clock.call, 0].max : nil
+            @condition.wait(@mutex, delay) unless @finished
+          end
+        end
+      end
+
+      def tick
+        return unless @event&.state == :active && @clock.call >= @next_tick
+
+        render(@event, waiting: @display ? SPINNER[@spinner % SPINNER.size] : true)
+        @spinner += 1
+        @next_tick = @clock.call + (@display ? SPINNER_INTERVAL : @heartbeat_interval)
+      end
+
+      def render(event, waiting: false)
+        return @display.render(event, waiting: waiting) if @display
+
+        message = self.class.clean_message(event.message)
+        text = format('[%<percent>3d%%] %<message>s%<wait>s', percent: event.percent, message: message,
+                                                              wait: waiting ? ' (still working)' : '')
+        @io.puts(text)
+        @io.flush
+      end
+    end
+  end
+end

data/lib/empeira/cli/proxy.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Empeira
+  module CLI
+    class Proxy < Base
+      desc 'show HOSTNAME', 'Explain the normal proxy destination policy for a hostname'
+      def show(hostname)
+        config = application.context.configuration.fetch('proxy')
+        resolver = Network::HostPolicy.new(config)
+        say "Effective proxy policy for #{hostname.downcase}"
+        say access_message(config)
+        display_list('Global', config.fetch('global'))
+        display_matches(resolver.matching(hostname))
+        display_list('Allowed', resolver.resolve(hostname))
+        say 'Managed bootstrap destinations are separate from this normal policy.'
+      end
+      no_commands do
+        def access_message(config)
+          return "All workspace nodes may use this policy after 'empeira up' reconciles the proxy." if
+            config.fetch('enabled')
+
+          'The normal workspace proxy is disabled.'
+        end
+
+        def display_matches(rules)
+          display_list('Matched rules', rules.map { |rule| rule.fetch('hosts').join(', ') })
+        end
+
+        def display_list(title, entries)
+          say "#{title}:"
+          entries.each { |entry| say "  #{entry}" }
+        end
+      end
+    end
+  end
+end

data/lib/empeira/cli/update.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Empeira
+  module CLI
+    class Update < Base
+      Updates::Service::TARGETS.each do |target|
+        desc target,
+             { 'all' => 'Update all managed targets, including Empeira (unavailable)',
+               'modules' => 'Synchronize Puppetfile module artifacts',
+               'images' => 'Refresh configured container image artifacts' }.fetch(target)
+        define_method(target) do
+          if target == 'all'
+            application.updates.update(target)
+          else
+            progressing("Updating #{target}...") { |app| app.updates.update(target) }
+          end
+        end
+      end
+    end
+  end
+end