glazed 0.1.0

data/lib/glazed/command/base.rb

@@ -0,0 +1,146 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'json'
+require 'dry/cli'
+require 'glazed'
+require 'glazed/must'
+require 'glazed/proto'
+require 'glazed/proto_json'
+require 'glazed/runner'
+require 'glazed/state_backends'
+require 'glazed/step_context'
+require 'glazed/validation'
+
+module Glazed
+  module Command
+    # Base of glazed's commands, giving them the output streams dry-cli
+    # injects (or the process's own when run directly).
+    class Base < Dry::CLI::Command
+      # Nodes processed in parallel when the config sets none.
+      DEFAULT_JOBS = 4 #: Integer
+      # Environment variable naming the config file when --config is omitted.
+      CONFIG_FILE_ENV = 'GLAZED_CONFIG_FILE' #: String
+
+      # @return [IO] standard output
+      #: () -> IO
+      private def out = instance_variable_get(:@out) || $stdout
+
+      # @return [IO] standard error
+      #: () -> IO
+      private def err = instance_variable_get(:@err) || $stderr
+
+      # Exits 1 with a message when neither --config nor {CONFIG_FILE_ENV} names the config file.
+      #
+      # @param config [String, nil] the --config option
+      # @param command [String] command name, for the message
+      # @return [String] path of the config file
+      #: (String? config, String command) -> String
+      private def config_path(config, command)
+        path = config || ENV.fetch(CONFIG_FILE_ENV, '')
+        return path unless path.empty?
+
+        err.puts "glazed #{command}: --config or #{CONFIG_FILE_ENV} is required"
+        exit 1
+      end
+
+      # @return [Proc] listener writing each event to standard error as a JSON line
+      #: () -> Runner::listener
+      private def json_listener
+        lock = Mutex.new
+        ->(event) { lock.synchronize { err.puts(JSON.generate(event)) } }
+      end
+
+      # @param config [Proto::V1::Config] the config
+      # @param path [String] config file, for the error message
+      # @return [Proto::V1::Orchestrator] the orchestrator settings
+      # @raise [Glazed::Error] when the config has none
+      #: (Proto::V1::Config config, String path) -> Proto::V1::Orchestrator
+      private def orchestrator_settings(config, path)
+        config.orchestrator or raise Glazed::Error, "#{path}: orchestrator is not configured"
+      end
+
+      # @param orchestration [Proto::V1::Orchestrator] the orchestrator settings
+      # @param names [Array<String>, nil] requested workflows; every orchestrated one when nil
+      # @return [Array<String>] the workflows, without duplicates
+      # @raise [Glazed::Error] when a requested workflow is not orchestrated
+      #: (Proto::V1::Orchestrator orchestration, Array[String]? names) -> Array[String]
+      private def select_orchestrated(orchestration, names)
+        orchestrated = orchestration.workflows.keys.sort
+        return orchestrated unless names
+
+        unknown = names - orchestrated
+        raise Glazed::Error, "not orchestrated workflows: #{unknown.join(', ')}" unless unknown.empty?
+
+        names.uniq
+      end
+
+      # @param orchestration [Proto::V1::Orchestrator] the orchestrator settings
+      # @param context [StepContext] configured storages
+      # @return [StateBackends::Base] the state backend
+      # @raise [Glazed::Error] when the backend cannot be built
+      #: (Proto::V1::Orchestrator orchestration, StepContext context) -> StateBackends::Base
+      private def state_backend(orchestration, context)
+        StateBackends.build(Must.because(orchestration.state) { 'validation requires orchestrator.state' }, context:)
+      end
+
+      # @param config [Proto::V1::Config] the config
+      # @return [Integer] nodes processed in parallel
+      #: (Proto::V1::Config config) -> Integer
+      private def default_jobs(config) = config.jobs.zero? ? DEFAULT_JOBS : config.jobs
+
+      # Reads the config, first requiring the features its `requires` lists so
+      # plugin settings types are known when it is decoded.
+      #
+      # @param path [String] config file
+      # @return [Proto::V1::Config] the config
+      # @raise [Glazed::Error] when `requires` is malformed, or the config does not decode
+      # @raise [InvalidMessage] when the config breaks the rules of its schema
+      # @raise [LoadError] when a required feature is missing
+      #: (String path) -> Proto::V1::Config
+      private def load_config(path)
+        json = ::File.read(path)
+        document = JSON.parse(json) #: untyped
+        requires = document.is_a?(Hash) ? document.fetch('requires', []) : []
+        unless requires.is_a?(Array) && requires.all?(String)
+          raise Glazed::Error, "#{path}: requires must be a list of strings"
+        end
+
+        requires.each { require it }
+        ProtoJson.load(Proto::V1::Config, json).tap { Validation.validate!(it, origin: path) }
+      rescue Google::Protobuf::ParseError, JSON::ParserError => e
+        hint = e.message.include?('Type was not found') ? '; list the gem providing that plugin type in requires' : ''
+        raise Glazed::Error, "#{path}: #{e.message}#{hint}"
+      end
+
+      # @param config [Proto::V1::Config] the config
+      # @param name [String, nil] requested workflow
+      # @return [Proto::V1::Workflow] the selected workflow
+      # @raise [Glazed::Error] when the name is unknown, or none is given and the config has not exactly one
+      #: (Proto::V1::Config config, String? name) -> Proto::V1::Workflow
+      private def select_workflow(config, name)
+        names = config.workflows.keys.sort
+        name ||= names.first if names.size == 1
+        raise Glazed::Error, "choose a workflow with --workflow: #{names.join(', ')}" unless name
+
+        config.workflows[name] or raise Glazed::Error, "no workflow named #{name.inspect}"
+      end
+
+      # @param nodes [Array<Proto::V1::Node>] every node in the inventory
+      # @param only [Array<String>] node names to keep; all when empty
+      # @return [Array<Proto::V1::Node>] the selected nodes
+      # @raise [Glazed::Error] when only names an unknown node
+      #: (Array[Proto::V1::Node] nodes, Array[String] only) -> Array[Proto::V1::Node]
+      private def select_nodes(nodes, only)
+        return nodes if only.empty?
+
+        unknown = only - nodes.map(&:name)
+        raise Glazed::Error, "unknown nodes: #{unknown.join(', ')}" unless unknown.empty?
+
+        nodes.select { only.include?(it.name) }
+      end
+    end
+  end
+end

data/lib/glazed/command/orchestrate.rb

@@ -0,0 +1,78 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'glazed/command/base'
+require 'glazed/must'
+require 'glazed/orchestrator'
+require 'glazed/proto'
+require 'glazed/sources'
+require 'glazed/state_backends'
+require 'glazed/step_context'
+require 'glazed/workflow'
+
+module Glazed
+  module Command
+    # `glazed orchestrate`: runs the orchestrator in the foreground until
+    # terminated, logging JSON lines to standard error. TERM or INT stops it
+    # after the current batch, and a second one interrupts the batch. HUP
+    # reloads the inventory.
+    class Orchestrate < Base
+      desc 'Run the orchestrated workflows for each node as it becomes due, until terminated'
+      option :config, aliases: ['-c'], desc: 'Config file, ProtoJSON of glazed.v1.Config; $GLAZED_CONFIG_FILE when omitted'
+      option :jobs, aliases: ['-j'], type: :integer, desc: 'Nodes processed in parallel'
+
+      # Runs the orchestrator until a signal stops it.
+      #
+      # @param config [String, nil] path of the config file; {Base::CONFIG_FILE_ENV} when nil
+      # @param jobs [Integer, nil] parallelism overriding the config
+      # @param _options [Hash] other options dry-cli passes, unused
+      # @return [void]
+      # @raise [Glazed::Error, Google::Protobuf::ParseError] when the config or inventory is invalid, or the state backend fails
+      # @raise [Interrupt] when a second TERM or INT interrupts a batch
+      #: (?config: String?, ?jobs: Integer?, **untyped _options) -> void
+      def call(config: nil, jobs: nil, **_options)
+        config = config_path(config, 'orchestrate')
+
+        settings = load_config(config)
+        orchestration = orchestrator_settings(settings, config)
+        listener = json_listener
+        context = StepContext.from_proto(settings.storages, listener:)
+        workflows = orchestration.workflows.keys.to_h { [it, Workflow.from_proto(select_workflow(settings, it), context:)] }
+        backend = state_backend(orchestration, context)
+        orchestrator = Orchestrator.new(
+          settings: orchestration, workflows:, backend:, inventory: -> { Sources.nodes(settings.inventory.to_a) },
+          jobs: jobs || default_jobs(settings), listener:,
+        )
+        with_traps(orchestrator) { orchestrator.run }
+      ensure
+        backend&.close
+      end
+
+      # Installs the signal handlers while the block runs.
+      #
+      # @param orchestrator [Orchestrator] the orchestrator to control
+      # @yieldreturn [void]
+      # @return [void]
+      #: (Orchestrator orchestrator) { () -> void } -> void
+      private def with_traps(orchestrator, &)
+        stopping = false #: bool
+        stop = proc do |_signo|
+          raise Interrupt if stopping
+
+          stopping = true
+          orchestrator.stop
+        end
+        previous = {
+          'TERM' => trap('TERM', &stop),
+          'INT' => trap('INT', &stop),
+          'HUP' => trap('HUP') { orchestrator.reload_inventory },
+        } #: Hash[String, untyped]
+        yield
+      ensure
+        previous&.each { |signal, handler| trap(signal, handler || 'DEFAULT') }
+      end
+    end
+  end
+end

data/lib/glazed/command/run.rb

@@ -0,0 +1,51 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'glazed/command/base'
+require 'glazed/proto'
+require 'glazed/runner'
+require 'glazed/sources'
+require 'glazed/step_context'
+require 'glazed/workflow'
+
+module Glazed
+  module Command
+    # `glazed run`: runs one workflow of the config against the inventory in
+    # this process. Nodes that fail a step are logged and skipped, and make the
+    # exit status 1.
+    class Run < Base
+      desc 'Run a workflow of the config against the inventory'
+      option :config, aliases: ['-c'], desc: 'Config file, ProtoJSON of glazed.v1.Config; $GLAZED_CONFIG_FILE when omitted'
+      option :workflow, aliases: ['-w'], desc: 'Workflow to run; optional when the config defines one'
+      option :only, type: :array, desc: 'Run only for these nodes, comma-separated'
+      option :jobs, aliases: ['-j'], type: :integer, desc: 'Nodes processed in parallel'
+
+      # Runs the workflow, exiting 1 when a node failed or --config is missing.
+      #
+      # @param config [String, nil] path of the config file; {Base::CONFIG_FILE_ENV} when nil
+      # @param workflow [String, nil] workflow name; the only one when nil
+      # @param only [Array<String>, nil] node names to run for; all when nil
+      # @param jobs [Integer, nil] parallelism overriding the config
+      # @param _options [Hash] other options dry-cli passes, unused
+      # @return [void]
+      # @raise [Glazed::Error, Google::Protobuf::ParseError] when the config, inventory or a batch step fails
+      #: (?config: String?, ?workflow: String?, ?only: Array[String]?, ?jobs: Integer?, **untyped _options) -> void
+      def call(config: nil, workflow: nil, only: nil, jobs: nil, **_options)
+        config = config_path(config, 'run')
+
+        settings = load_config(config)
+        listener = json_listener
+        context = StepContext.from_proto(settings.storages, listener:)
+        steps = Workflow.from_proto(select_workflow(settings, workflow), context:)
+        nodes = select_nodes(Sources.nodes(settings.inventory.to_a), only || [])
+
+        jobs ||= default_jobs(settings)
+        result = Runner.new(workflow: steps, jobs:, listener:).call(nodes)
+        out.puts "completed #{result.states.size} of #{nodes.size} nodes, #{result.changed.size} changed, #{result.failures.size} failed"
+        exit 1 unless result.failures.empty?
+      end
+    end
+  end
+end

data/lib/glazed/command/send_signal.rb

@@ -0,0 +1,69 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'time'
+require 'google/protobuf'
+require 'glazed/command/base'
+require 'glazed/must'
+require 'glazed/orchestrator'
+require 'glazed/proto'
+require 'glazed/sources'
+require 'glazed/state_backends'
+require 'glazed/step_context'
+require 'glazed/validation'
+
+module Glazed
+  module Command
+    # `glazed signal`: asks the orchestrator to run nodes soon, such as after
+    # their configuration changed. The signal is recorded in the state backend
+    # for every orchestrated workflow, or those chosen, with each workflow's
+    # debounce, so `glazed orchestrate` need not be reachable. It prints when
+    # each node is due.
+    class SendSignal < Base
+      desc 'Make nodes due soon for glazed orchestrate'
+      argument :nodes, type: :array, required: true, desc: 'Names of the nodes'
+      option :config, aliases: ['-c'], desc: 'Config file, ProtoJSON of glazed.v1.Config; $GLAZED_CONFIG_FILE when omitted'
+      option :workflow, aliases: ['-w'], type: :array, desc: 'Signal only these orchestrated workflows, comma-separated'
+      option :source, default: 'manual', desc: 'What sent the signal, recorded as the reason the node is due'
+      option :now, type: :boolean, default: false, desc: 'Make the nodes due now, without the debounce delay'
+
+      # Records the signals.
+      #
+      # @param nodes [Array<String>] node names
+      # @param config [String, nil] path of the config file; {Base::CONFIG_FILE_ENV} when nil
+      # @param workflow [Array<String>, nil] workflows to signal; every orchestrated one when nil
+      # @param source [String] what sent the signal
+      # @param now [Boolean] whether to skip the debounce delay
+      # @param _options [Hash] other options dry-cli passes, unused
+      # @return [void]
+      # @raise [Glazed::Error, Google::Protobuf::ParseError] when the config is invalid, a node is unknown, or the state backend fails
+      #: (nodes: Array[String], ?config: String?, ?workflow: Array[String]?, ?source: String, ?now: bool, **untyped _options) -> void
+      def call(nodes:, config: nil, workflow: nil, source: 'manual', now: false, **_options)
+        config = config_path(config, 'signal')
+
+        settings = load_config(config)
+        orchestration = orchestrator_settings(settings, config)
+        workflows = select_orchestrated(orchestration, workflow)
+        select_nodes(Sources.nodes(settings.inventory.to_a), nodes)
+        context = StepContext.from_proto(settings.storages, listener: json_listener)
+        backend = state_backend(orchestration, context)
+        at = Time.now
+        signals = nodes.map do |node|
+          Proto::V1::Signal.new(node:, source:, received_at: Google::Protobuf::Timestamp.from_time(at), immediate: now).tap { Validation.validate!(it) }
+        end
+        workflows.each do |name|
+          debounce = orchestration.workflows[name]&.debounce
+          records = Orchestrator.signal(backend:, workflow: name, signals:, debounce:, now: at)
+          nodes.uniq.each do |node|
+            due_at = Must.because(records.fetch(node).due_at) { 'validation requires due_at' }
+            out.puts "#{node} #{name} due at #{due_at.to_time.utc.iso8601}"
+          end
+        end
+      ensure
+        backend&.close
+      end
+    end
+  end
+end

data/lib/glazed/command/status.rb

@@ -0,0 +1,179 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'glazed/command/base'
+require 'glazed/orchestrator'
+require 'glazed/proto'
+require 'glazed/proto_json'
+require 'glazed/state_backends/base'
+require 'glazed/step_context'
+
+module Glazed
+  module Command
+    # `glazed status`: prints the orchestration state of each workflow and
+    # node, as a table or as ProtoJSON lines. The exit status is 1 when a
+    # listed node's last run failed or it is overdue, so it can serve as a
+    # monitoring check.
+    class Status < Base
+      #: type row = Array[String]
+
+      # Headings of the table columns.
+      HEADINGS = ['WORKFLOW', 'NODE', 'STATUS', 'DUE', 'REASON', 'LAST RUN', 'RESULT'].freeze #: Array[String]
+
+      desc 'Print when each node runs next and how its last run went'
+      option :config, aliases: ['-c'], desc: 'Config file, ProtoJSON of glazed.v1.Config; $GLAZED_CONFIG_FILE when omitted'
+      option :workflow, aliases: ['-w'], type: :array, desc: 'Show only these orchestrated workflows, comma-separated'
+      option :only, type: :array, desc: 'Show only these nodes, comma-separated'
+      option :failing, type: :boolean, default: false, desc: 'Show only nodes whose last run failed'
+      option :json, type: :boolean, default: false, desc: 'Print each record as a line of ProtoJSON of glazed.v1.NodeSchedule'
+
+      # Prints the records, exiting 1 when one of them is failing or overdue.
+      #
+      # @param config [String, nil] path of the config file; {Base::CONFIG_FILE_ENV} when nil
+      # @param workflow [Array<String>, nil] workflows to show; every orchestrated one when nil
+      # @param only [Array<String>, nil] nodes to show; all when nil
+      # @param failing [Boolean] whether to show only nodes whose last run failed
+      # @param json [Boolean] whether to print ProtoJSON lines instead of a table
+      # @param _options [Hash] other options dry-cli passes, unused
+      # @return [void]
+      # @raise [Glazed::Error, Google::Protobuf::ParseError] when the config is invalid or the state backend fails
+      #: (?config: String?, ?workflow: Array[String]?, ?only: Array[String]?, ?failing: bool, ?json: bool, **untyped _options) -> void
+      def call(config: nil, workflow: nil, only: nil, failing: false, json: false, **_options)
+        config = config_path(config, 'status')
+        settings = load_config(config)
+        orchestration = orchestrator_settings(settings, config)
+        workflows = select_orchestrated(orchestration, workflow)
+        backend = state_backend(orchestration, StepContext.from_proto(settings.storages, listener: json_listener))
+        records = workflows.flat_map { backend.list(it) }
+        records.select! { only.include?(it.node) } if only
+        records.select!(&:last_failed) if failing
+
+        now = Time.now
+        poll_seconds = orchestration.poll_seconds.zero? ? Orchestrator::DEFAULT_POLL : orchestration.poll_seconds
+        if json
+          records.each { out.puts ProtoJson.dump(it) }
+        else
+          print_table(records.map { row(it, now:, poll_seconds:) })
+        end
+        exit 1 if records.any? { it.last_failed || status(it, now:, poll_seconds:) == 'overdue' }
+      ensure
+        backend&.close
+      end
+
+      # @param rows [Array<Array<String>>] cells of each row, the last being free-form notes
+      # @return [void]
+      #: (Array[Status::row] rows) -> void
+      private def print_table(rows)
+        widths = HEADINGS.each_index.map { |index| [HEADINGS.fetch(index), *rows.map { it.fetch(index) }].map(&:length).max || 0 }
+        [HEADINGS, *rows].each do |cells|
+          columns = HEADINGS.each_index.map { |index| cells.fetch(index).ljust(widths.fetch(index)) }
+          out.puts [*columns, *cells.drop(HEADINGS.size)].join('  ').rstrip
+        end
+      end
+
+      # @param record [Proto::V1::NodeSchedule] the record
+      # @param now [Time] current time
+      # @param poll_seconds [Integer] seconds between the orchestrator's checks for due nodes
+      # @return [Array<String>] the cells, then the notes
+      #: (Proto::V1::NodeSchedule record, now: Time, poll_seconds: Integer) -> Status::row
+      private def row(record, now:, poll_seconds:)
+        status = status(record, now:, poll_seconds:)
+        due = time(record.due_at)
+        due_cell = due ? clock(due, now) : '-'
+        due_cell = "#{due_cell} (#{relative(due, now)})" if due && status != 'running'
+        [record.workflow, record.node, status, due_cell, record.due_reason, last_run(record, now:), result(record), notes(record, now:).join('; ')]
+      end
+
+      # @param record [Proto::V1::NodeSchedule] the record
+      # @param now [Time] current time
+      # @param poll_seconds [Integer] seconds between the orchestrator's checks for due nodes
+      # @return [String] "running", "overdue" when due for more than a poll interval, "due", or "waiting"
+      #: (Proto::V1::NodeSchedule record, now: Time, poll_seconds: Integer) -> String
+      private def status(record, now:, poll_seconds:)
+        return 'running' if Orchestrator::Policy.running?(record, now)
+
+        due = time(record.due_at)
+        return 'waiting' if due.nil? || due > now
+
+        now - due > poll_seconds ? 'overdue' : 'due'
+      end
+
+      # @param record [Proto::V1::NodeSchedule] the record
+      # @param now [Time] current time
+      # @return [String] start of the latest run with its duration, or "-" when it never ran
+      #: (Proto::V1::NodeSchedule record, now: Time) -> String
+      private def last_run(record, now:)
+        started = time(record.last_started_at)
+        return '-' unless started
+
+        finished = time(record.last_finished_at)
+        duration = finished && finished >= started ? format('%.1fs', finished - started) : 'running'
+        "#{clock(started, now)} (#{duration})"
+      end
+
+      # @param record [Proto::V1::NodeSchedule] the record
+      # @return [String] "ok", "failed ×N", or "-" when it never finished a run
+      #: (Proto::V1::NodeSchedule record) -> String
+      private def result(record)
+        return "failed ×#{record.consecutive_failures}" if record.last_failed
+        return '-' unless record.last_finished_at
+
+        'ok'
+      end
+
+      # @param record [Proto::V1::NodeSchedule] the record
+      # @param now [Time] current time
+      # @return [Array<String>] the last error, a pending signal and the lease, where present
+      #: (Proto::V1::NodeSchedule record, now: Time) -> Array[String]
+      private def notes(record, now:)
+        notes = [] #: Array[String]
+        notes << record.last_error if record.last_failed && !record.last_error.empty?
+        window = time(record.signal_window_started_at)
+        started = time(record.last_started_at)
+        notes << "signal pending since #{clock(window, now)}" if window && (started.nil? || window > started)
+        lease_until = time(record.lease_until)
+        notes << "lease #{record.lease_owner} until #{clock(lease_until, now)}" if !record.lease_owner.empty? && lease_until
+        notes
+      end
+
+      # @param timestamp [Google::Protobuf::Timestamp, nil] the timestamp
+      # @return [Time, nil] the time, or nil when unset
+      #: (Google::Protobuf::Timestamp? timestamp) -> Time?
+      private def time(timestamp) = Orchestrator::Policy.time(timestamp)
+
+      # @param time [Time] the time
+      # @param now [Time] current time
+      # @return [String] the UTC time of day, with the date when it is not today
+      #: (Time time, Time now) -> String
+      private def clock(time, now)
+        utc = time.getutc
+        utc.strftime('%F') == now.getutc.strftime('%F') ? utc.strftime('%TZ') : utc.strftime('%FT%TZ')
+      end
+
+      # @param time [Time] the time
+      # @param now [Time] current time
+      # @return [String] such as "in 8m52s" or "4m16s ago"
+      #: (Time time, Time now) -> String
+      private def relative(time, now)
+        seconds = (time - now).round
+        seconds.negative? ? "#{span(-seconds)} ago" : "in #{span(seconds)}"
+      end
+
+      # @param seconds [Integer] non-negative seconds
+      # @return [String] the span in its two largest units, such as "2d3h", "4m16s" or "9s"
+      #: (Integer seconds) -> String
+      private def span(seconds)
+        minutes, secs = seconds.divmod(60)
+        hours, mins = minutes.divmod(60)
+        days, hrs = hours.divmod(24)
+        return "#{days}d#{hrs}h" if days.positive?
+        return "#{hours}h#{mins}m" if hours.positive?
+        return "#{minutes}m#{secs}s" if minutes.positive?
+
+        "#{secs}s"
+      end
+    end
+  end
+end

data/lib/glazed/command/version.rb

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'glazed/command/base'
+require 'glazed/version'
+
+module Glazed
+  module Command
+    # `glazed version`: prints the version.
+    class Version < Base
+      desc 'Print the version'
+
+      # @param _options [Hash] options dry-cli passes, unused
+      # @return [void]
+      #: (**untyped _options) -> void
+      def call(**_options)
+        out.puts Glazed::VERSION
+      end
+    end
+  end
+end

data/lib/glazed/command.rb

@@ -0,0 +1,39 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'dry/cli'
+require 'glazed'
+require 'glazed/command/orchestrate'
+require 'glazed/command/run'
+require 'glazed/command/send_signal'
+require 'glazed/command/status'
+require 'glazed/command/version'
+
+module Glazed
+  # Commands of the glazed executable.
+  module Command
+    extend Dry::CLI::Registry
+
+    register 'orchestrate', Orchestrate
+    register 'run', Run
+    register 'signal', SendSignal
+    register 'status', Status
+    register 'version', Version, aliases: ['--version']
+
+    # Runs a command line.
+    #
+    # @param argv [Array<String>] command line arguments
+    # @param out [IO] standard output
+    # @param err [IO] standard error, which receives JSON log lines
+    # @return [Integer] exit status
+    #: (Array[String] argv, ?out: IO, ?err: IO) -> Integer
+    def self.start(argv, out: $stdout, err: $stderr)
+      Dry::CLI.new(self).call(arguments: argv, out:, err:)
+      0
+    rescue SystemExit => e
+      e.status
+    end
+  end
+end

data/lib/glazed/command_result.rb

@@ -0,0 +1,26 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'glazed'
+
+module Glazed
+  # Output of one command run on a device.
+  class CommandResult
+    # @param command [String] command line that was run
+    # @param output [String] output without the echoed command or trailing prompt
+    #: (command: String, output: String) -> void
+    def initialize(command:, output:)
+      @command = command #: String
+      @output = output #: String
+    end
+
+    # @return [String] command line that was run
+    #: String
+    attr_reader :command
+    # @return [String] output without the echoed command or trailing prompt
+    #: String
+    attr_reader :output
+  end
+end