xolo-admin 2.0.2 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78c42e6fb9e17f593f77705e340642273e4f83d70234a809fdef98101555cbe0
-  data.tar.gz: 54286e2ebccf3dbb76e28d9916da8b593792ccd1691aaebc0ff31f5313d4a6b4
+  metadata.gz: ace6e6d8f0ac4d0ed085f2037803869d1b35ea3ff4efb53b3651dc3faafa5c25
+  data.tar.gz: 39cae6de70ea1a0e90c9a12e2e80b4502b27715bfcedbbf991b1239eec69bb1c
 SHA512:
-  metadata.gz: e43eb8c13033590db47a1b3a8a51480956ee606f5f59a2f857ae38f9e382abb1a4b29f9213c8df4131ca53937553ad09ecea7262df7f3b1a5cbd96b16ab8d0b8
-  data.tar.gz: 9ad24a86d2248d8767aa9c088129071f6d3fdc2aebff88c544584eefa2e1f274e1488dffc601c463727d2131694f33ab8f7a87da12bfb998cea26a0069b93954
+  metadata.gz: '059aa31ea917298e5aef01c64625b9fa8b1b539c181217ec7dffbfcc51e334c4d0e2ee43dff2e9d4908ddd9867a0b8c1c683685c9039300283f9d99c37b7d159'
+  data.tar.gz: 5dbc53d110470af587c234efebd060baf590872f17613ef5c3dc688a3bde85a94e544e6824ec92cc428b5352d2c4b93a6483bc27fa3e5c6c24579cdb48ff4c65

data/data/client/xolo

@@ -54,9 +54,15 @@ JAMF='/usr/local/bin/jamf'
 # The path to the client data json file
 CLIENT_DATA_JSON_FILE="/Library/Application Support/xolo/client-data.json"
 
+# The path to the test client data json file, from a text xolo server
+TEST_CLIENT_DATA_JSON_FILE="/Library/Application Support/xolo/test-client-data.json"
+
 # The jamf policy trigger to update the client data
 UPDATE_CLIENT_DATA_TRIGGER='update-xolo-client-data'
 
+# The jamf policy trigger to update the test client data
+TEST_UPDATE_CLIENT_DATA_TRIGGER='test-update-xolo-client-data'
+
 # In the CLI args, titles and versions are separated by the first
 # occurrence of the equals sign
 TITLE_VERSION_SEPARATOR='='
@@ -141,6 +147,10 @@ Options:
   -v, --verbose:     Enable verbose mode, extra information will be printed.
   -d, --debug:       Enable debug mode, extra debug information will be printed.
                      Implies --verbose.
+  -t, --test         If your site has a "test" xolo server running via the same
+                     Jamf Pro server, this causes 'xolo' to only see data, titles,
+                     policies, etc, from test xolo server, not the production server.
+                     Setting the XOLO_TEST_MODE env. variable does the same thing.
   -r, --recon:       With 'install' or 'uninstall' run a 'jamf recon' after the
                      operation completes successfully.
   -n, --no-versions: With the 'list-titles' and 'list-installed' commands,
@@ -152,6 +162,8 @@ Commands:
   install, i <title>[=<version>] [<title2>[=<version2>] ...]
     Install a title, or specific version thereof (e.g. a version currently in pilot)
     If no version is specified, the currently released version will be installed.
+    If you are only installing only one specific version of one title, you can
+    omit the =, e.g. install <title> <version>.
 
   uninstall, u <title> [<title2> ...]
     Uninstall a title, if possible. Not all titles are uninstallable via xolo.
@@ -221,6 +233,7 @@ function parse_cli() {
     {h,H,-help}=show_help \
     {v,-verbose}=be_verbose \
     {d,-debug}=debugging_on \
+    {t,-test}=test_mode \
     {n,-no-versions}=no_versions \
     {r,-recon}=do_recon \
     {V,-version}=show_xolo_version || \
@@ -230,22 +243,44 @@ function parse_cli() {
   show_help=$show_help[-1]
   be_verbose=$be_verbose[-1]
   debugging_on=$debugging_on[-1]
+  test_mode=$test_mode[-1]
   no_versions=$no_versions[-1]
   do_recon=$do_recon[-1]
   show_xolo_version=$show_xolo_version[-1]
 
+  # test mode can be triggered by an env var
+  [[ -n "$XOLO_TEST_MODE" ]] && test_mode=1
+
   # if debugging is on, verbose is also on
   [[ -n $debugging_on ]] && be_verbose=1
 
   command=$1
   [[ ${#@} -gt 0 ]] && shift
 
+  # the remaining positional parameters as an array called targets
+  # It'll either be exactly 1 item: title
+  # or exactly 2 items containing no '=' : title, version
+  # or exactly 2 items containing no '=' : title, title
+  # or any number if items in the form: title[=version]  where the =version is optional.
   targets=("${(@)@}")
 
+  # if targets has exactly 2 items, and neither of them contains
+  # '=' and the second one isn't an existing title then treat
+  # them as the title and a version and reset 'targets' to be 'title=version'
+  if [[ "$#targets" == 2  ]] \
+    && [[ "$targets[1]" != *"$TITLE_VERSION_SEPARATOR"* ]] \
+    && [[ "$targets[2]" != *"$TITLE_VERSION_SEPARATOR"* ]] \
+    && ! echo "$(all_xolo_titles)" | grep -qE "^${targets[2]}$"  ; then
+
+    targets=("$targets[1]=$targets[2]")
+  fi
+
   debug "Parsed command line:"
   debug "..show_help is: $show_help"
   debug "..be_verbose is: $be_verbose"
   debug "..debugging_on is: $debugging_on"
+  debug "..test_mode is: $test_mode"
+  [[ -n "$XOLO_TEST_MODE" ]] && debug "  ..via XOLO_TEST_MODE env."
   debug "..no_versions is: $no_versions"
   debug "..show_xolo_version is: $show_xolo_version"
 
@@ -258,6 +293,9 @@ function parse_cli() {
 #################################
 function parse_title_and_version() {
   local arg=$1
+  unset title_is_valid
+  unset version_is_valid
+
   debug "Parsing title and version from arg: '$arg'"
 
   if [[ "$arg" == *"$TITLE_VERSION_SEPARATOR"* ]] ; then
@@ -381,7 +419,7 @@ app.includeStandardAdditions = true;
 
 // run() is automatically executed when the program is called, and will print any output returned.
 function run() {
-    var parsed_data = JSON.parse(app.read("${CLIENT_DATA_JSON_FILE}"));
+    var parsed_data = JSON.parse(app.read("${client_data_json_file}"));
     var result;
 
     // the line below will sub-in whatever code we were passed
@@ -761,7 +799,7 @@ function refresh_client_data() {
 
   [[ "$command" == 'refresh' ]] && say "Refreshing client data..." || debug "Refreshing client data..."
 
-  run_jamf_policy_trigger $UPDATE_CLIENT_DATA_TRIGGER
+  run_jamf_policy_trigger "$update_client_data_trigger"
 
   client_data_refreshed=1
 }
@@ -769,9 +807,13 @@ function refresh_client_data() {
 # validate that the title exists
 ###############################
 function validate_title() {
+
   # if we've already validated the title, we're done
   [[ -n "$title_is_valid" ]] && return
 
+  # use passed arg if needed
+  [[ -z "$title" ]] && title=$1
+
   debug "Validating title: $title"
 
   # die if no title given
@@ -806,7 +848,7 @@ function validate_version() {
   all_versions=$(versions_for_title $title)
   debug "All versions for title $title:\n$all_versions"
   # [[ $all_versions =~ (^|\n)$version($|\n) ]] || die "No such version: $version"
-  echo "$all_versions" | grep -q "^$version$" || die "No such version: $version"
+  echo "$all_versions" | grep -q "^$version$" || die "No such version '$version' for title '$title'"
   version_is_valid=1
 }
 
@@ -1156,6 +1198,10 @@ function expire() {
 ###############################
 
 function main() {
+  # defaults
+  client_data_json_file="$CLIENT_DATA_JSON_FILE"
+  update_client_data_trigger="$UPDATE_CLIENT_DATA_TRIGGER"
+
   # Parse the command line
   parse_cli "$@"
 
@@ -1171,10 +1217,16 @@ function main() {
     exit 0
   fi
 
+  # use the test data file if in test mode
+  if [[ -n "$test_mode" ]] ; then
+    client_data_json_file="$TEST_CLIENT_DATA_JSON_FILE"
+    update_client_data_trigger="$TEST_UPDATE_CLIENT_DATA_TRIGGER"
+  fi
+
   if [[ "$command" != "refresh" ]] ; then
     # If we're not refreshing, we need to have the client data file
     # and it needs to be up to date
-    [[ -f "$CLIENT_DATA_JSON_FILE" ]] || die "No client data file found at $CLIENT_DATA_JSON_FILE.\nPlease run the 'refresh' command to update the client data."
+    [[ -f "$client_data_json_file" ]] || die "No client data file found at $client_data_json_file.\nPlease run the 'refresh' command to update the client data."
   fi
 
   [[ -z "$command" ]] && die "No command given.\nUsage: $USAGE\nUse --help for more information."

data/lib/xolo/admin/command_line.rb

@@ -398,6 +398,7 @@ module Xolo
               opt opt_key, desc, short: deets[:cli], type: type, required: required, multi: deets[:multi]
             end # opts_to_use.each
           end # if cmd_opts
+          conflicts :subscribed, :managed if cmd == Xolo::Admin::Options::LIST_TITLES_CMD
         end # Optimist.options
       end
 

data/lib/xolo/admin/options.rb

@@ -198,6 +198,52 @@ module Xolo
       TARGET_TITLE_PLACEHOLDER = Xolo::Admin::Title::TARGET_TITLE_PLACEHOLDER
       TARGET_VERSION_PLACEHOLDER = 'TARGET_VERSION_PH'
 
+      LIST_TITLES_OPTIONS = {
+        subscribed: {
+          label: 'Subscribed Only',
+          cli: :s,
+          type: :boolean,
+          validate: :validate_boolean,
+          default: false,
+          desc: <<~ENDDESC
+            Show only 'subscribed' titles. Can be combined with --autopkg.
+          ENDDESC
+        },
+
+        managed: {
+          label: 'Managed Only',
+          cli: :m,
+          type: :boolean,
+          validate: :validate_boolean,
+          default: false,
+          desc: <<~ENDDESC
+            Show only 'managed' titles. Can be combined with --autopkg.
+          ENDDESC
+        },
+
+        autopkg: {
+          label: 'AutoPkg Only',
+          cli: :a,
+          type: :boolean,
+          validate: :validate_boolean,
+          default: false,
+          desc: <<~ENDDESC
+            Show only titles configured for AutoPkg. Can be combined with --subscribed or --managed.
+          ENDDESC
+        },
+
+        pilots: {
+          label: 'Pilots Only',
+          cli: :p,
+          type: :boolean,
+          validate: :validate_boolean,
+          default: false,
+          desc: <<~ENDDESC
+            Show only titles with pending pilot (un-released) versions. Use 'list-versions' to see details for a title. Can be combined with --subscribed or --managed.
+          ENDDESC
+        }
+      }.freeze
+
       PATCH_REPORT_OPTIONS = {
         summary: {
           label: 'Summary Only',
@@ -410,7 +456,7 @@ module Xolo
         LIST_TITLES_CMD => {
           desc: 'List all software titles.',
           display: LIST_TITLES_CMD,
-          opts: {},
+          opts: LIST_TITLES_OPTIONS,
           arg_banner: :none,
           process_method: :list_titles,
           target: :none

data/lib/xolo/admin/processing.rb

@@ -211,16 +211,27 @@ module Xolo
           return
         end
 
-        report_title = 'All titles in Xolo'
-        header = %w[Title Created By SSvc? Released Latest]
+        type = opts_to_process.subscribed ? ' subscribed' : nil
+        type ||= opts_to_process.managed ? ' managed' : nil
+        autopkg = opts_to_process.autopkg ? ' autopkg' : nil
+        pilots = opts_to_process.pilots ? ' with unreleased pilots' : nil
+
+        report_title = "All#{type}#{autopkg} titles in Xolo#{pilots}"
+
+        titles.select! { |t| t.subscribed? } if opts_to_process.subscribed
+        titles.reject! { |t| t.subscribed? } if opts_to_process.managed
+        titles.select! { |t| t.autopkg_recipe } if opts_to_process.autopkg
+        titles.select! { |t| pending_pilots? t } if opts_to_process.pilots
+
+        header = %w[Title Created By SSvc? Latest Released]
         data = titles.map do |t|
           [
             t.title,
             t.creation_date.to_date,
             t.created_by,
             t.self_service || false,
-            t.released_version,
-            t.latest_version
+            t.latest_version,
+            t.released_version
           ]
         end
         data.sort_by! { |d| d[0].downcase } # sort by title
@@ -230,6 +241,16 @@ module Xolo
         handle_processing_error e
       end
 
+      # @param title [Xolo::Admin::Title] The title in question
+      # @return [Boolean] Does a given Title object have pilots?
+      ###########################
+      def pending_pilots?(title)
+        return false if title.version_order.pix_empty?
+        return false if title.released_version == title.version_order.first
+
+        true
+      end
+
       # Add a title to Xolo
       #
       # @return [void]
@@ -487,16 +508,19 @@ module Xolo
           return
         end
 
-        report_title = "All versions of '#{cli_cmd.title}' in Xolo"
+        report_title = "All versions of '#{cli_cmd.title}' in Xolo.  ** = No .pkg uploaded"
         header = %w[Vers Created By Released By Status]
         data = versions.sort_by(&:creation_date).map do |v|
+          no_pkg = v.pkg_to_upload.pix_empty? && v.jamf_pkg_file.pix_empty?
+          status = no_pkg ? "#{v.status} **" : v.status
+
           [
             v.version,
             v.creation_date.to_date,
             v.created_by,
             v.release_date&.to_date,
             v.released_by,
-            v.status
+            status
           ]
         end
         show_text generate_report(data, header_row: header, title: report_title)
@@ -750,6 +774,9 @@ module Xolo
           # description is handled specially below
           next if attr == :description
 
+          # only show patch_source and title_id if subscribed
+          next if %i[patch_source title_id].include?(attr) && !title.subscribed?
+
           value = title.send attr
           value = value.join(Xolo::COMMA_JOIN) if value.is_a? Array
           puts "- #{deets[:label]}: #{value}".pix_word_wrap

data/lib/xolo/admin/title.rb

@@ -169,7 +169,10 @@ module Xolo
       # @return [Hash] the response body from the server
       ####################
       def release(cnx = self.cnx, version:)
-        resp = cnx.patch "#{SERVER_ROUTE}/#{title}/release/#{version}", {}
+        resp = cnx.patch "#{SERVER_ROUTE}/#{title}/release/#{URI::Parser.new.escape version}", {}
+        ### the CGI escape one doesn't seem to work with, e.g. "7.1.5 (84650)"
+        # resp = cnx.patch "#{SERVER_ROUTE}/#{title}/release/#{CGI.escape version}", {}
+
         resp.body
       end
 

data/lib/xolo/admin/version.rb

@@ -50,7 +50,9 @@ module Xolo
       ####################
       def self.server_route(title, version = nil)
         route = SERVER_ROUTE.sub(Xolo::Admin::Title::TARGET_TITLE_PLACEHOLDER, title)
-        route << "/#{version}" if version
+        route << "/#{URI::Parser.new.escape(version)}" if version
+        ### the CGI escape one doesn't seem to work with, e.g. "7.1.5 (84650)"
+        # route << "/#{CGI.escape(version)}" if version
         route
       end
 

data/lib/xolo/core/base_classes/title.rb

@@ -474,6 +474,8 @@ module Xolo
             desc: <<~ENDDESC
               One or more Jamf Computer Groups whose members will automatically have new versions installed or updated for testing before it is released.
 
+              These groups affect both the initial installation of and updates to a title when a version is added, before it is released.
+
               These computers will be used for testing not just the software, but the installation process itself. Exclusions win, so computers that are also in an excluded group for the title will not be used as pilots.
 
               Pilot groups can also be defined per version, in which case these will be ignored. Defining them in the title is useful for subscribed titles, where new versions are created automatically.
@@ -505,7 +507,9 @@ module Xolo
             readline: :jamf_computer_group_names,
             invalid_msg: 'Invalid release group(s). Must exist in Jamf and not be excluded.',
             desc: <<~ENDDESC
-              One or more Jamf Computer Groups whose members will automatically have this title installed when new versions are released.
+              One or more Jamf Computer Groups whose members will automatically have this title installed.
+
+              These groups affect the _initial_ installation of a title when a version is released. Any Mac with the title installed, will get updates (if not excluded) regardless of the release-groups.
 
               If your Xolo administrators allow it, you can use '#{Xolo::TARGET_ALL}' to auto-install on all computers that aren't excluded. If not, you'll be told how to request setting release groups to '#{Xolo::TARGET_ALL}'.
 
@@ -534,7 +538,7 @@ module Xolo
             desc: <<~ENDDESC
               One or more Jamf Computer Groups whose members are not allowed to install this title.
 
-              When a computer is in one of these groups, the title is not available even if the computer is in a pilot or release group.
+              When a computer is in one of these groups, the title is not available at all, for installation or updates, even if the computer is in a pilot or release group.
 
               When using the --excluded-groups CLI option, you can specify more than one group by using the option more than once, or by providing a single option value with the groups separated by commas.
 
@@ -663,6 +667,7 @@ module Xolo
               It will never be available to excluded computers.
 
               Self Service is not available for titles with the release_group 'all'.
+              To remove the self-service option, use --no-self-service.
             ENDDESC
           },
 
@@ -799,7 +804,7 @@ module Xolo
           # @!attribute ted_id_number
           #   @return [Integer] The Windoo::SoftwareTitle#softwareTitleId
           ted_id_number: {
-            label: 'Title Editor ID Number',
+            label: 'Title Editor ID',
             type: :integer,
             cli: false,
             changelog: false,
@@ -812,7 +817,7 @@ module Xolo
           # @!attribute jamf_patch_title_id
           #   @return [Integer] The Windoo::SoftwareTitle#softwareTitleId
           jamf_patch_title_id: {
-            label: 'The Jamf ID Number of this Patch Title',
+            label: 'Jamf Patch Title ID',
             type: :integer,
             cli: false,
             changelog: false,

data/lib/xolo/core/base_classes/version.rb

@@ -170,6 +170,7 @@ module Xolo
             changelog: true,
             desc: <<~ENDDESC
               The installation of this version requires the computer to reboot. Users will be notified before installation.
+              To remove the reboot option, use --no-reboot.
             ENDDESC
           },
 
@@ -186,6 +187,7 @@ module Xolo
             changelog: true,
             desc: <<~ENDDESC
               The installer for this version is a full installer, not an incremental patch that must be installed on top of an earlier version.
+              To remove the standalone option, use --no-standalone.
             ENDDESC
           },
 
@@ -217,6 +219,7 @@ module Xolo
               use them as a killapp by specifying '#{USE_TITLE_FOR_KILLAPP}'
 
               If not using --walkthru you can use --killapps multiple times
+              To remove all killapps, use '#{Xolo::NONE}'.
             ENDDESC
           },
 
@@ -237,6 +240,8 @@ module Xolo
               This can cause problems if that unknown version is actually newer than this version, e.g. a beta or pre-release version, or when the app has a 'self-update' mechanism that installs newer versions outside of Jamf Patch before it is aware of them.
 
               But sometimes it may be desirable to have all unknown versions updated to this version, e.g. when the title is a helper app that is not regularly updated, or when the title is being newly managed by Xolo/Jamf Patch and you want to get all existing installations onto this version.
+
+              To remove the patch-unknown option, use --no-patch-unknown.
             ENDDESC
           },
 
@@ -262,7 +267,7 @@ module Xolo
 
               When using the --pilot-groups CLI option, you can specify more than one group by using the option more than once, or by providing a single option value with the groups separated by commas.
 
-              When adding a new version, the pilot groups from the previous version will be inherited if you don't specify any. To make the new version have no pilot groups use '#{Xolo::NONE}'.
+              When adding a new version, the pilot groups from the previous version will be inherited if you don't specify any. To make the version have no pilot groups use '#{Xolo::NONE}'.
 
               NOTE: Any non-excluded computer can be used for piloting at any time by manually installing the yet-to-be-released version using `sudo xolo install <title> <version>`.  The members of the pilot groups are just the ones that will have it auto-installed.
             ENDDESC

data/lib/xolo/core/version.rb

@@ -12,7 +12,7 @@ module Xolo
 
     module Version
 
-      VERSION = '2.0.2'.freeze
+      VERSION = '2.1.0'.freeze
 
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: xolo-admin
 version: !ruby/object:Gem::Version
-  version: 2.0.2
+  version: 2.1.0
 platform: ruby
 authors:
 - Chris Lasell
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-16 00:00:00.000000000 Z
+date: 2026-08-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday