xolo-admin 1.0.0

data/lib/xolo/admin/version.rb

@@ -0,0 +1,221 @@
+# 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 Admin
+
+    # A version/patch as used by xadm.
+    # This adds cli and walkthru UI, as well as
+    # an interface to the Xolo Server for Title
+    # objects.
+    class Version < Xolo::Core::BaseClasses::Version
+
+      # This is the server path for dealing with titles
+      # POST to add a new one
+      # GET to get a list of versions for a title
+      # GET .../<version> to get the data for a single version
+      # PUT .../<version> to update a version with new data
+      # DELETE .../<version> to delete a version from the title
+      SERVER_ROUTE = "/titles/#{Xolo::Admin::Title::TARGET_TITLE_PLACEHOLDER}/versions"
+
+      # Server route for uploading packages
+      UPLOAD_PKG_ROUTE = 'pkg'
+
+      # Modification of the ATTRIBUTES constant for how they are handled
+      # in the admin app
+      ATTRIBUTES[:min_os][:default] = proc { Xolo::Admin::Options.default_min_os }
+
+      # Class Methods
+      #############################
+      #############################
+
+      # @return [Hash{Symbol: Hash}] The ATTRIBUTES that are available as CLI & walkthru options
+      def self.cli_opts
+        @cli_opts ||= ATTRIBUTES.select { |_k, v| v[:cli] }
+      end
+
+      # get the server route to a specific version (or the version list) for a title
+      # @param title [String] the title
+      # @param version [String] the version to fetch
+      # @param cnx [Faraday::Connection] The connection to use, must be logged in already
+      # @return [Xolo::Admin::Title]
+      ####################
+      def self.server_route(title, version = nil)
+        route = SERVER_ROUTE.sub(Xolo::Admin::Title::TARGET_TITLE_PLACEHOLDER, title)
+        route << "/#{version}" if version
+        route
+      end
+
+      # @return [Array<String>] The currently known versions of a title on the server
+      #############################
+      def self.all_versions(title, cnx)
+        resp = cnx.get server_route(title)
+        resp.body
+      end
+
+      # @return [Array<Xolo::Admin::Version>] The currently known versions of a title on the server
+      #############################
+      def self.all_version_objects(title, cnx)
+        resp = cnx.get server_route(title)
+        resp.body.map { |vd| Xolo::Admin::Version.new vd }
+      end
+
+      # Does a version of a title exist on the server?
+      # @param title [String] the title
+      # @param version [String] the version
+      # @param cnx [Faraday::Connection] The connection to use, must be logged in already
+      # @return [Boolean]
+      #############################
+      def self.exist?(title, version, cnx)
+        all_versions(title, cnx).include? version
+      end
+
+      # Fetch a version of a title from the server
+      # @param title [String] the title
+      # @param version [String] the version to fetch
+      # @param cnx [Faraday::Connection] The connection to use, must be logged in already
+      # @return [Xolo::Admin::Title]
+      ####################
+      def self.fetch(title, version, cnx)
+        resp = cnx.get server_route(title, version)
+        new resp.body
+      end
+
+      # Deploy a version to desired computers and groups via MDM
+      #
+      # @param cnx [Faraday::Connection] The connection to use, must be logged in already
+      # @param groups [Array<String, Integer>] The groups to deploy to
+      # @param computers [Array<String, Integer>] The computers to deploy to
+      #
+      # @return [Hash] The response from the server
+      ####################
+      def self.deploy(title, version, cnx, groups: [], computers: [])
+        raise ArgumentError, 'Must provide at least one group or computer' if groups.pix_empty? && computers.pix_empty?
+
+        route = "#{server_route(title, version)}/deploy"
+        content = { groups: groups, computers: computers }
+        resp = cnx.post(route) { |req| req.body = content }
+        resp.body
+      end
+
+      # Delete a version of a title from the server
+      # @param title [String] the title
+      # @param version [String] the version to delete
+      # @param cnx [Faraday::Connection] The connection to use, must be logged in already
+      # @return [Hash] the response body, parsed JSON
+      ####################
+      def self.delete(title, version, cnx)
+        resp = cnx.delete server_route(title, version)
+        resp.body
+      end
+
+      # Attributes
+      ######################
+      ######################
+
+      # Constructor
+      ######################
+      ######################
+
+      # Instance Methods
+      #############################
+      #############################
+
+      # The server route for this version, after it exists on the server
+
+      # Add this version to the server
+      # @param cnx [Faraday::Connection] The connection to use, must be logged in already
+      # @return [Hash] the response from the server
+      ####################
+      def add(cnx)
+        resp = cnx.post self.class.server_route(title), to_h
+        resp.body
+      end
+
+      # Update this version to the server
+      # @param cnx [Faraday::Connection] The connection to use, must be logged in already
+      # @return [Hash] the response from the server
+      ####################
+      def update(cnx)
+        resp = cnx.put self.class.server_route(title, version), to_h
+        resp.body
+      end
+
+      # Repair this version
+      # @param cnx [Faraday::Connection] The connection to use, must be logged in already
+      # @return [Hash] the response body from the server
+      ####################
+      def repair(cnx)
+        resp = cnx.post "#{self.class.server_route(title, version)}/repair"
+        resp.body
+      end
+
+      # Delete this title from the server
+      # @param cnx [Faraday::Connection] The connection to use, must be logged in already
+      # @return [Hash] the response from the server
+      ####################
+      def delete(cnx)
+        self.class.delete title, version, cnx
+        # already returns resp.body
+      end
+
+      # Fetch a hash of URLs for the GUI pages for this title
+      # @param cnx [Faraday::Connection] The connection to use, must be logged in already
+      # @return [Hash{String => String}] page_name => url
+      ####################
+      def gui_urls(cnx)
+        resp = cnx.get "#{self.class.server_route(title, version)}/urls"
+        resp.body
+      end
+
+      # Upload a .pkg (or zipped bundle pkg) for this version
+      # At this point, the jamf_pkg_file attribute
+      # will containt the local file path.
+      #
+      # @param upload_cnx [Xolo::Admin::Connection] The server connection
+      #
+      # @return [Faraday::Response] The server response
+      ##################################
+      def upload_pkg(upload_cnx)
+        return unless pkg_to_upload.is_a? Pathname
+
+        # route = "#{UPLOAD_PKG_ROUTE}/#{title}/#{version}"
+        route = "#{self.class.server_route(title, version)}/#{UPLOAD_PKG_ROUTE}"
+
+        # TODO: Update this to the more modern correct class
+        # upfile = Faraday::UploadIO.new(
+        #   pkg_to_upload.to_s,
+        #   'application/octet-stream',
+        #   pkg_to_upload.basename.to_s
+        # )
+
+        upfile = Faraday::Multipart::FilePart.new(pkg_to_upload.expand_path.to_s, 'application/octet-stream')
+
+        content = { file: upfile }
+        upload_cnx.post(route) { |req| req.body = content }
+      end
+
+      # Get the Patch Report data for this version
+      # It's the JPAPI report data with each hash having a frozen: key added
+      #
+      # @param cnx [Faraday::Connection] The connection to use, must be logged in already
+      # @return [Array<Hash>] Data for each computer with this version of this title installed
+      ##################################
+      def patch_report_data(cnx)
+        resp = cnx.get "#{self.class.server_route(title, version)}/patch_report"
+        resp.body
+      end
+
+    end # class Title
+
+  end # module Admin
+
+end # module Xolo

data/lib/xolo/admin.rb

@@ -0,0 +1,139 @@
+# 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
+
+# Requires
+#########################################
+
+# This file is the entry point for loading the Xolo Admin code
+#
+# You can and should require the convenience file 'xolo-admin.rb'
+#
+#    require 'xolo-admin'
+#
+
+# Standard Libraries
+######
+require 'openssl'
+
+# Monkeypatch OpenSSL::SSL::SSLContext to ignore unexpected EOF errors
+# happens with openssl v3 ??
+# see https://stackoverflow.com/questions/76183622/since-a-ruby-container-upgrade-we-expirience-a-lot-of-opensslsslsslerror
+if OpenSSL::SSL.const_defined?(:OP_IGNORE_UNEXPECTED_EOF)
+  OpenSSL::SSL::SSLContext::DEFAULT_PARAMS[:options] |= OpenSSL::SSL::OP_IGNORE_UNEXPECTED_EOF
+end
+
+require 'openssl'
+require 'faraday'
+require 'faraday/multipart'
+require 'highline'
+
+# Monkeypatch OpenSSL::SSL::SSLContext to ignore unexpected EOF errors
+# happens with openssl v3 ??
+# see https://stackoverflow.com/questions/76183622/since-a-ruby-container-upgrade-we-expirience-a-lot-of-opensslsslsslerror
+if OpenSSL::SSL.const_defined?(:OP_IGNORE_UNEXPECTED_EOF)
+  OpenSSL::SSL::SSLContext::DEFAULT_PARAMS[:options] |= OpenSSL::SSL::OP_IGNORE_UNEXPECTED_EOF
+end
+
+# Yes we're using a OpenStruct for our @opts, even though it's very slow.
+# It isn't so slow that it's a problem for processing a CLI tool.
+# The benefit is being able to use either Hash-style references
+# e.g. opts[key] or method-style when you know the key e.g. opts.title
+require 'ostruct'
+require 'open3'
+require 'singleton'
+require 'yaml'
+require 'shellwords'
+require 'tempfile'
+require 'readline'
+require 'io/console'
+
+# Use optimist for CLI option processing
+# https://rubygems.org/gems/optimist
+#
+# This version modified to allow 'insert_blanks' which
+# puts blank lines between each option in the help output.
+# See comments in the required file for details.
+#
+require 'optimist_with_insert_blanks'
+
+# Xolo Admin code - order matters here
+# more loaded below
+require 'xolo/core'
+require 'xolo/admin/configuration'
+
+module Xolo
+
+  module Admin
+
+    # Constants
+    ##########################
+    ##########################
+
+    EXECUTABLE_FILENAME = 'xadm'
+
+    # if a streaming line contains this text, we bail out instead of
+    # continuing any processing
+    STREAMING_OUTPUT_ERROR = 'ERROR'
+
+    # Module Methods
+    ##########################
+    ##########################
+
+    # when this module is included
+    def self.included(includer)
+      Xolo.verbose_include includer, self
+    end
+
+    # @return [Xolo::Admin::Configuration] our config, available via the module
+    ########################
+    def self.config
+      Xolo::Admin::Configuration.instance
+    end
+
+    # Instance Methods
+    ##########################
+    ##########################
+
+    # @return [String] the usage
+    ########################
+    def usage
+      @usage ||= "#{EXECUTABLE_FILENAME} [global-options] command [target] [command-options]"
+    end
+
+    # @return [Xolo::Admin::Configuration] our config available via the admin app instance
+    ########################
+    def config
+      Xolo::Admin::Configuration.instance
+    end
+
+  end
+
+end
+
+# the rest of the Xolo Admin code - order matters here
+require 'xolo/admin/credentials'
+
+require 'xolo/admin/title'
+require 'xolo/admin/version'
+
+require 'xolo/admin/options'
+require 'xolo/admin/interactive'
+require 'xolo/admin/command_line'
+require 'xolo/admin/processing'
+require 'xolo/admin/progress_history'
+require 'xolo/admin/validate'
+
+require 'xolo/admin/connection'
+require 'xolo/admin/cookie_jar'
+require 'xolo/admin/jamf_pro'
+require 'xolo/admin/title_editor'
+
+# A small monkeypatch that allows Readline completion
+# of Highline.ask to optionally use a prompt and be
+# case insensitive
+require 'xolo/admin/highline_terminal'

data/lib/xolo-admin.rb

@@ -0,0 +1,8 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+
+# Shortcut xolo-admin => xolo/admin
+require 'xolo/admin'

metadata

@@ -0,0 +1,139 @@
+--- !ruby/object:Gem::Specification
+name: xolo-admin
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Chris Lasell
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-09-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: faraday-multipart
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: pixar-ruby-extensions
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: highline
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+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_.
+
+  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
+executables:
+- xadm
+extensions: []
+extra_rdoc_files:
+- README.md
+- LICENSE.txt
+files:
+- LICENSE.txt
+- README.md
+- bin/xadm
+- lib/xolo-admin.rb
+- lib/xolo/admin.rb
+- lib/xolo/admin/command_line.rb
+- lib/xolo/admin/configuration.rb
+- lib/xolo/admin/connection.rb
+- lib/xolo/admin/cookie_jar.rb
+- lib/xolo/admin/credentials.rb
+- lib/xolo/admin/highline_terminal.rb
+- lib/xolo/admin/interactive.rb
+- lib/xolo/admin/jamf_pro.rb
+- lib/xolo/admin/options.rb
+- lib/xolo/admin/processing.rb
+- lib/xolo/admin/progress_history.rb
+- lib/xolo/admin/title.rb
+- lib/xolo/admin/title_editor.rb
+- lib/xolo/admin/validate.rb
+- lib/xolo/admin/version.rb
+homepage: https://pixaranimationstudios.github.io/xolo-home/
+licenses:
+- LicenseRef-LICENSE.txt
+metadata: {}
+post_install_message:
+rdoc_options:
+- "--title"
+- Xolo-Admin
+- "--line-numbers"
+- "--main"
+- README.md
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.11
+signing_key:
+specification_version: 4
+summary: Automation and Standardization for Jamf Pro Patch Management
+test_files: []