xolo-admin 1.0.0 → 1.0.1

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/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 = '1.0.1'.freeze
+
+    end
+
+  end
+
+end # module

data/lib/xolo/core.rb

@@ -0,0 +1,46 @@
+# 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
+
+# Load the core xolo functionality
+#
+# This is done automatically when you `require 'xolo/admin'` or
+# `require 'xolo/server'`
+
+# Ruby Standard Libraries
+######
+require 'English'
+require 'date'
+require 'time'
+require 'pathname'
+require 'json'
+
+# Other Gems to include at this level
+require 'pixar-ruby-extensions'
+
+# Internal requires - order matters
+require 'xolo/core/loading'
+require 'xolo/core/version'
+require 'xolo/core/constants'
+require 'xolo/core/exceptions'
+
+# The main module
+module Xolo
+
+  extend Xolo::Core::Loading
+  include Xolo::Core::Version
+  include Xolo::Core::Constants
+  include Xolo::Core::Exceptions
+
+end # module Xolo
+
+require 'xolo/core/json_wrappers'
+require 'xolo/core/base_classes/configuration'
+require 'xolo/core/base_classes/server_object'
+require 'xolo/core/base_classes/title'
+require 'xolo/core/base_classes/version'
+require 'xolo/core/output'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: xolo-admin
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Chris Lasell
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-09-28 00:00:00.000000000 Z
+date: 2025-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -70,14 +70,12 @@ description: |
   == Xolo
   Xolo (sorta pronounced 'show-low') is an HTTPS server and set of command-line tools for macOS that provide automatable access to the software deployment and patch management aspects of {Jamf Pro}[https://www.jamf.com/products/jamf-pro/] and the {Jamf Title Editor}[https://learn.jamf.com/en-US/bundle/title-editor/page/About_Title_Editor.html]. It enhances Jamf Pro's abilities in many ways:
 
-    - Management of titles and versions/patches is scriptable and automatable, allowing developers and admins to integrate with CI/CD workflows.
-    - Simplifies and standardizes the complex, multistep manual process of managing titles and patches using the Title Editor and Patch Management web interfaces.
-    - Client installs can be performed by remotely via ssh and/or MDM
-    - Automated pre-release piloting of new versions/patches
-    - Titles can be expired (auto-uninstalled) after a period of disuse, reclaiming unused licenses.
-    - And more!
-
-  "Xolo" is the short name for the Mexican hairless dog breed {'xoloitzcuintle'}[https://en.wikipedia.org/wiki/Xoloitzcuintle] (show-low-itz-kwint-leh), as personified by Dante in the 2017 Pixar film _Coco_.
+  * Management of titles and versions/patches is scriptable and automatable, allowing developers and admins to integrate with CI/CD workflows.
+  * Simplifies and standardizes the complex, multistep manual process of managing titles and patches using the Title Editor and Patch Management web interfaces.
+  * Client installs can be performed by remotely via ssh and/or MDM
+  * Automated pre-release piloting of new versions/patches
+  * Titles can be expired (auto-uninstalled) after a period of disuse, reclaiming unused licenses.
+  * And more!
 
   The xolo-admin gem packages the code needed to run 'xadm', the command-line tool for system administrators to deploy and maintain software titles using Xolo.
 email: xolo@pixar.com
@@ -91,6 +89,8 @@ files:
 - LICENSE.txt
 - README.md
 - bin/xadm
+- data/client/xolo
+- lib/optimist_with_insert_blanks.rb
 - lib/xolo-admin.rb
 - lib/xolo/admin.rb
 - lib/xolo/admin/command_line.rb
@@ -108,6 +108,17 @@ files:
 - lib/xolo/admin/title_editor.rb
 - lib/xolo/admin/validate.rb
 - lib/xolo/admin/version.rb
+- lib/xolo/core.rb
+- lib/xolo/core/base_classes/configuration.rb
+- lib/xolo/core/base_classes/server_object.rb
+- lib/xolo/core/base_classes/title.rb
+- lib/xolo/core/base_classes/version.rb
+- lib/xolo/core/constants.rb
+- lib/xolo/core/exceptions.rb
+- lib/xolo/core/json_wrappers.rb
+- lib/xolo/core/loading.rb
+- lib/xolo/core/output.rb
+- lib/xolo/core/version.rb
 homepage: https://pixaranimationstudios.github.io/xolo-home/
 licenses:
 - LicenseRef-LICENSE.txt