xolo-admin 1.0.0 → 2.0.2

data/lib/xolo/core/constants.rb

@@ -0,0 +1,85 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+
+# frozen_string_literal: true
+
+module Xolo
+
+  module Core
+
+    # Constants useful throughout Xolo
+    #####################################
+    module Constants
+
+      # Empty strings are used in various places
+      BLANK = ''
+
+      # The value to use when unsetting an option
+      NONE = 'none'
+
+      OK = 'OK'
+
+      ERROR = 'ERROR'
+
+      # Several things use x
+      X = 'x'
+
+      # CLI options and other things use dashes
+      DASH = '-'
+
+      # Several things use dots
+      DOT = '.'
+
+      # Cancelling is often an option
+      CANCEL = 'Cancel'
+
+      # and we check for things ending with .app
+      DOTAPP = '.app'
+
+      DOTJSON = '.json'
+
+      # These are handy for testing values without making new arrays, strings, etc every time.
+      TRUE_FALSE = [true, false].freeze
+
+      # lots of things get split on commmas
+      COMMA_SEP_RE = /\s*,\s*/.freeze
+
+      # lots of things get joined with commas
+      COMMA_JOIN = ', '
+
+      # Some things get split on semicolons
+      SEMICOLON_SEP_RE = /\s*;\s*/.freeze
+
+      # Once a thing has been uploaded and saved, this
+      # is what the server returns as the  attr value
+      ITEM_UPLOADED = 'uploaded'
+
+      DOT_PKG = '.pkg'
+
+      UNKNOWN = 'unknown'
+
+      # Installer packages must have one of these extensions
+      OK_PKG_EXTS = [DOT_PKG]
+
+      # The value to use when all computers are the release-targets
+      # and for all manual-install policies
+      TARGET_ALL = 'all'
+
+      # Title Types
+      MANAGED = :managed
+      SUBSCRIBED = :subscribed
+      TITLE_TYPES = [MANAGED, SUBSCRIBED].freeze
+      DEFAULT_TITLE_TYPE = :managed
+
+      # when this module is included
+      def self.included(includer)
+        Xolo.verbose_include includer, self
+      end
+
+    end # module constants
+
+  end # module core
+
+end # module Xolo

data/lib/xolo/core/exceptions.rb

@@ -0,0 +1,52 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+#
+
+module Xolo
+
+  module Core
+
+    module Exceptions
+
+      # General errors
+
+      class MissingDataError < RuntimeError; end
+
+      class InvalidDataError < RuntimeError; end
+
+      class NoSuchItemError < RuntimeError; end
+
+      class UnsupportedError < RuntimeError; end
+
+      class KeychainError < RuntimeError; end
+
+      class ActionRequiredError < RuntimeError; end
+
+      # Connections & Access
+
+      class ConnectionError < RuntimeError; end
+
+      class NotConnectedError < ConnectionError; end
+
+      class TimeoutError < ConnectionError; end
+
+      class AuthenticationError < ConnectionError; end
+
+      class PermissionError < ConnectionError; end
+
+      class InvalidTokenError < ConnectionError; end
+
+      class ServerError < ConnectionError; end
+
+      # Parsing errors
+
+      class DisallowedYAMLDumpClass; end
+
+    end # module Exceptions
+
+  end # module Core
+
+end # module Xolo

data/lib/xolo/core/json_wrappers.rb

@@ -0,0 +1,43 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+#
+
+# frozen_string_literal: true
+
+# main module
+module Xolo
+
+  module Core
+
+    # constants and methods for consistent JSON processing on the server
+    module JSONWrappers
+
+      # when this module is extended
+      def self.extended(extender)
+        Xolo.verbose_extend extender, self
+      end
+
+      # when this module is included
+      def self.included(includer)
+        Xolo.verbose_include includer, self
+      end
+
+      # A wrapper for JSON.parse that always uses :symbolize_names
+      # def self.parse_json(str)
+      #   JSON.parse str, symbolize_names: true
+      # end
+
+      # A wrapper for JSON.parse that always uses :symbolize_names
+      # and ensures UTF-8 encoding
+      def parse_json(str)
+        JSON.parse str.force_encoding('UTF-8'), symbolize_names: true
+      end
+
+    end # JSON
+
+  end # Core
+
+end # module Xolo

data/lib/xolo/core/loading.rb

@@ -0,0 +1,59 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+
+# frozen_string_literal: true
+
+module Xolo
+
+  module Core
+
+    module Loading
+
+      # touch this file to make mixins send text to stderr as things load
+      # or get mixed in
+      VERBOSE_LOADING_FILE = Pathname.new('/tmp/xolo-verbose-loading')
+
+      # Or, set this ENV var to also make mixins send text to stderr
+      VERBOSE_LOADING_ENV = 'XOLO_VERBOSE_LOADING'
+
+      def self.extended(extender)
+        Xolo.verbose_extend extender, self
+      end
+
+      # Only look at the filesystem once.
+      def verbose_loading?
+        return @verbose_loading unless @verbose_loading.nil?
+
+        @verbose_loading = VERBOSE_LOADING_FILE.file?
+        @verbose_loading ||= ENV.include? VERBOSE_LOADING_ENV
+        @verbose_loading
+      end
+
+      # Send a message to stderr if verbose loading is enabled
+      def load_msg(msg)
+        warn msg if verbose_loading?
+      end
+
+      # Mention that a module is being included into something
+      def verbose_include(includer, includee)
+        load_msg "--> #{includer} is including #{includee}"
+      end
+
+      # Mention that a module is being extended into something
+      def verbose_extend(extender, extendee)
+        load_msg "--> #{extender} is extending #{extendee}"
+      end
+
+      # Mention that a module is being extended into something
+      def verbose_inherit(child_class, parent_class)
+        load_msg "--> #{child_class} is a Subclass inheriting from #{parent_class}"
+      end
+
+    end # module
+
+  end # module
+
+end # module Xolo

data/lib/xolo/core/output.rb

@@ -0,0 +1,292 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+
+# frozen_string_literal: true
+
+require 'io/console'
+
+module Xolo
+
+  module Core
+
+    # Methods for formattng and sending output to stdout
+    # Should be included in classes as needed
+    #
+    # NOTE: Help output is auto-generated by 'optimist'
+    # The methods here are mostly for presenting info like
+    # columnizd lists and reports and the like.
+    module Output
+
+      # Constants
+      #############################
+      #############################
+
+      # This is used when we are not outputting to a terminal
+      # usually we're being piped or not running in a terminal
+      # so the lines should be as long as they want
+      DEFAULT_LINE_WIDTH = 2000
+
+      # Module methods
+      #
+      # These are available as module methods but not as 'helper'
+      # methods in sinatra routes & views.
+      #
+      ##############################
+      ##############################
+
+      # when this module is included
+      ##############################
+      def self.included(includer)
+        Xolo.verbose_include includer, self
+      end
+
+      # when this module is extended
+      def self.extended(extender)
+        Xolo.verbose_extend extender, self
+      end
+
+      # Instance methods
+      #
+      # These are available directly in sinatra routes and views
+      #
+      ##############################
+      ##############################
+
+      # @return [Integer] how many rows high is our terminal?
+      #########################
+      def terminal_height
+        IO.console.winsize.first
+      end
+
+      # @return [Integer] how many columns wide is our terminal?
+      #########################
+      def terminal_width
+        IO.console.winsize.last
+      end
+
+      # @return [Integer] how wide is our word wrap? terminal-width minus 5
+      #########################
+      def terminal_word_wrap
+        @terminal_word_wrap ||= terminal_width - 5
+      end
+
+      # format a multi-line value by  prepending the desired indentation
+      # to all but the first line, which is expected to be indented in-place where
+      # its being used.
+      #
+      # @param value [String] the value to format
+      # @param indent [Integer] the number of spaces to indent all but the first line
+      # @return [String] the formatted value
+      #######################
+      def format_multiline_indent(value, indent:)
+        value = value.to_s
+        return value unless value.include? "\n"
+
+        lines = value.split("\n")
+        lines[1..-1].each { |line| line.prepend ' ' * indent }
+        lines.join("\n")
+      end
+
+      # TODO: Move this out of Xolo::Core
+      # Display a list of items in as many columns as possible
+      # based on terminal width, e.g. with 3 cols:
+      #
+      #   a thing        another thing    third thing
+      #   thing2         line2 thing      third line 2
+      #   line3 thing    another one      and yet a 3rd
+      #   oh my line4    4 line ok?       yes, this is it
+      #
+      # and if the list is longer than terminal height,
+      # pipe it through 'less'
+      #
+      # @param header [String] A string to display at the top prepended with a '#'
+      #    and appended with a newline and a line of ######'s of the same length.
+      #
+      # @param list [Array<String>] the items to list
+      #
+      # @return [void]
+      ############################
+      def list_in_cols(header, list)
+        longest_list_item = list.map(&:size).max
+        use_columns = (longest_list_item + 5) < terminal_width
+
+        list_to_display = use_columns ? highline_cli.list(list, :columns_down) : list.join("\n")
+
+        output = +"# #{header}\n"
+        output << '#' * (terminal_width - 5)
+        output << "\n"
+        output << list_to_display
+
+        show_text output
+      end
+
+      # Generate a report of rowed/columned data, either fixed-width or tab-delimited.
+      #
+      # Title and header lines are pre-pended with '# ' for easier exclusion
+      # when using the report as input for some other program.
+      # If the :type is :fixed, so will the column header line.
+      # (however, for parsing this data, try using the --json option)
+      #
+      # @param lines [Array<Array>] the rows and columns of data
+      #
+      # @param type [Symbol] :fixed or :tab, defaults to :fixed
+      #
+      # @params title [String] a descriptive text or title, shown above the
+      #   column headers. Every line is pre-pended with '# '.
+      #   Only used on :fixed reports.
+      #
+      # @params header_row [Array<String>] the column headers. optional.
+      #
+      # @return [String] the formatted report.
+      #
+      ############################
+      def generate_report(lines, type: :fixed, header_row: [], title: nil)
+        return Xolo::BLANK if lines.pix_empty?
+
+        raise ArgumentError, 'The first argument must be an Array' unless lines.is_a?(Array)
+        raise ArgumentError, 'The header_row must be an Array' unless header_row.is_a? Array
+
+        # tab delim is easy
+        if type == :tab
+          report_tab = header_row.join("\t")
+          lines.each { |line| report_tab += "\n#{line.join("\t")}" }
+          return report_tab.strip
+        end # if :tab
+
+        # below here, fixed width
+
+        line_width, format_str = width_and_format(lines, header_row)
+
+        # title if given
+        report = title ? +"# #{title}\n" : +''
+
+        unless header_row.empty?
+          unless header_row.size == lines[0].size
+            raise ArgumentError,
+                  "Header row must have #{lines[0].count} items"
+          end
+
+          # then the header line if given
+          report +=  format_str % header_row
+          # add a separator
+          report +=  '#' + ('-' * (line_width - 1)) + "\n"
+        end
+        # add the rows
+        lines.each { |line| report += format_str % line }
+
+        report
+      end # generate report
+
+      # Given an Array of Arrays representing rows and columns of data,
+      # figure out the appropriate line-width for the longest line
+      # and the printf format string to create the columns
+      #
+      #
+      # @param lines [Array<Array>] The rows and columns of data
+      #
+      # @param header_row [Array] An optional header row to include in the
+      #   width calculation.
+      #
+      # @return [Array<Integer, String>] the line width and format string
+      #
+      ############################
+      def width_and_format(lines, header_row = [])
+        # below here, fixed width
+        format_str = +''
+        line_width = 0
+        header_row[0] = "# #{header_row[0]}"
+
+        col_widths(lines, header_row).each do |w|
+          # make sure there's a space between columns
+          col_width = w + 1
+
+          # add the column to the printf format
+          format_str += "%-#{col_width}s"
+          line_width += col_width
+        end
+        format_str += "\n"
+
+        # if needed, limit the total line width for the header the width of the terminal
+        max_width = $stdout.tty? ? terminal_word_wrap : DEFAULT_LINE_WIDTH
+        line_width = max_width if line_width > max_width
+
+        [line_width, format_str]
+      end
+
+      # Given an Array of Arrays representing rows and columns of data
+      # figure out the widest width of each column and return an array
+      # of integers representing those widths
+      #
+      # @param data [Array<Array>] The rows and columns of data
+      #
+      # @param header_row [Array] An optional header row to include in the
+      #   width calculation.
+      #
+      # @return [Array<Integer>] the max widths of each column of data.
+      #
+      ############################
+      def col_widths(data, header_row = [])
+        widths = header_row.map { |c| c.to_s.length }
+        data.each do |row|
+          row.each_index do |col|
+            this_width = row[col].to_s.length
+            widths[col] = this_width if this_width > widths[col].to_i
+          end # do field
+        end # do line
+        widths
+      end
+
+      # Should a given string be displayed via /usr/bin/less?
+      # true if stdout is a tty AND the string is > (terminal height - 2)
+      # The - 2 accounts for the final newline and an extra line at the
+      # bottom of the terminal, for better visual results
+      #########################
+      def use_less?(text)
+        $stdout.tty? && text.lines.size > (terminal_height - 2)
+      end
+
+      # Send a string to the terminal, possibly piping it through 'less'
+      # if the number of lines is greater than the number of terminal lines
+      #
+      # @param text[String] the text to send to the terminal
+      #
+      # @param show_help[Boolean] should the text have a line at the top
+      #   showing basic 'less' key commands.
+      #
+      # @result [void]
+      #
+      ############################
+      def show_text(text, show_help = true)
+        unless use_less?(text)
+          puts text
+          return
+        end
+
+        if show_help
+          help = "# -- Using /usr/bin/less: ' ' next, 'b' prev, 'q' exit, 'h' help --"
+          text = "#{help}\n#{text}"
+        end
+
+        # point stdout through less, print, then restore stdout
+        less = IO.popen('/usr/bin/less', 'w')
+
+        begin
+          less.puts text
+
+        # this catches the quitting of 'less' before all the output
+        # is displayed
+        rescue Errno::EPIPE
+          true
+        ensure
+          less&.close
+        end
+      end
+
+    end
+
+  end
+
+end # module

data/lib/xolo/core/security_cmd.rb

@@ -0,0 +1,128 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+#
+
+# frozen_string_literal: true
+
+# main module
+module Xolo
+
+  module Core
+
+    # Personal credentials for users of 'xadm', stored in the login keychain
+    #
+    module SecurityCmd
+
+      # Constants
+      ##############################
+      ##############################
+
+      # The security command
+      SEC_COMMAND = '/usr/bin/security'
+
+      # exit status when the login keychain can't be accessed because we aren't in a GUI session
+      SEC_STATUS_NO_GUI_ERROR = 36
+
+      # exit status when the keychain password provided is incorrect
+      SEC_STATUS_AUTH_ERROR = 51
+
+      # exit status when the desired item isn't found in the keychain
+      SEC_STATUS_NOT_FOUND_ERROR = 44
+
+      # Module methods
+      ##############################
+      ##############################
+
+      # when this module is included
+      def self.included(includer)
+        Xolo.verbose_include includer, self
+      end
+
+      # Instance Methods
+      ##########################
+      ##########################
+
+      # Run the security command in interactive mode on a given keychain,
+      # passing in a subcommand and its arguments. so that they don't appear in the
+      # `ps` output
+      #
+      # @param cmd [String] the subcommand being passed to 'security' with
+      #   all needed options. It will not be visible outide this process, so
+      #   its OK to put passwords into the options.
+      #
+      # @return [String] the stdout of the 'security' command.
+      #
+      ######
+      def run_security(cmd)
+        output = Xolo::BLANK
+        errs = Xolo::BLANK
+
+        Open3.popen3("#{SEC_COMMAND} -i") do |stdin, stdout, stderr, wait_thr|
+          # pid = wait_thr.pid # pid of the started process.
+          stdin.puts cmd
+          stdin.close
+
+          output = stdout.read
+          errs = stderr.read
+
+          @security_exit_status = wait_thr.value # Process::Status object returned.
+        end
+
+        # exit 44 is 'The specified item could not be found in the keychain'
+        return output.chomp if @security_exit_status.success?
+
+        case @security_exit_status.exitstatus
+        when SEC_STATUS_AUTH_ERROR
+          raise Xolo::KeychainError, 'Problem accessing login keychain. Is it locked?'
+
+        when SEC_STATUS_NOT_FOUND_ERROR
+          raise Xolo::NoSuchItemError, "No xolo admin password. Please run 'xadm config'"
+
+        else
+          errs.chomp!
+          errs =~ /: returned\s+(-?\d+)$/
+          errnum = Regexp.last_match(1)
+          desc = errnum ? security_error_desc(errnum) : errs
+          desc ||= errs
+          raise Xolo::KeychainError, "#{desc.gsub("\n", '; ')}; exit status #{@security_exit_status.exitstatus}"
+        end # case
+      end # run_security
+
+      # use `security error` to get a description of an error number
+      ##############
+      def security_error_desc(num)
+        desc = `#{SEC_COMMAND} error #{num}`
+        return if desc.include?('unknown error')
+
+        desc.chomp.split(num).last
+      rescue
+        nil
+      end
+
+      # given a string, wrap it in single quotes and escape internal single quotes
+      # and backslashes so it can be used in the interactive 'security' command
+      #
+      # @param str[String] the string to escape
+      #
+      # @return [String] the escaped string
+      ###################
+      def security_escape(str)
+        # first escape backslashes
+        str = str.to_s.gsub '\\', '\\\\\\'
+
+        # then single quotes
+        str.gsub! "'", "\\\\'"
+
+        # if other things need escaping, add them here
+
+        "'#{str}'"
+      end # security_escape
+
+    end # module Prefs
+
+  end # module Admin
+
+end # module Xolo

data/lib/xolo/core/version.rb

@@ -0,0 +1,21 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+#
+
+# main module
+module Xolo
+
+  module Core
+
+    module Version
+
+      VERSION = '2.0.2'.freeze
+
+    end
+
+  end
+
+end # module