depot3 3.0.8 → 3.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0f2b0abc1414a252659c6d595bf3283bf1b7a8e2
-  data.tar.gz: 1a01a64aa7a219af0899dae23b8626d646d00ee1
+  metadata.gz: c3958145701408de91742321b631220d28616638
+  data.tar.gz: 46cfaa84e02925dc7d3ea47d7616cb395ab4e2ab
 SHA512:
-  metadata.gz: eb799803790a7b79b80db8e52beecdf9b768af16eb36592aaa746cdfa9307cc7e3a1263ce817749aa7b9935c90d614743f986801c929646ff0f023300fa01017
-  data.tar.gz: a6cf663b32cdec3a3746586e904aa49cd57f4427187432510a1a56e5c7c32653e989b972870c62c6a5978075fa8cef0afe1a8e1f35b30e3c75d223189118ec63
+  metadata.gz: 3e37917a62941a884946bea3e32425d1a1731098c2f6d0b03aa6373e9375b1173bb4aaaa2dc2877e8739b28359513ce7ed8a8127540d4ec6ad57b96de4fd3f22
+  data.tar.gz: bde22daae9f593443f68c4a71375e5e3624acebc38a639cded1159bc7440e014aa5d04ef9fbacca7cac0c10d8cb27eaeb12a3a98135eb32227a022254b061ae1

data/CHANGES.md

@@ -1,5 +1,25 @@
 # Change History
 
-## v3.0.0 - 2016-04-04
+## v3.0.9 - 2016-04-11
 
-Planned initial open source release
+- d3: better text feedback during manual installs.
+- Package.all_filenames: limit list to d3 packages, not all JSS packages.
+- Client::Receript.add\_receipt: log "replaced" only when really replacing.
+- d3helper: clean up rcpt import, add pkg ids, admin name.
+- README: better contact info
+- lots of comment changes for YARD parsing fix
+- Package::Validate.check\_for\_exlusions: bugfix
+- Added D3::DEBUG_FILE support for d3, d3admin, & d3helper. Used getting debug logging/output when d3 command is embedded in other tools. If the file /tmp/d3debug-on exists, it's the same using the --debug option
+- d3: actions that don't need server connections can be done witout root: list-installed, list-manual, list-pilot, list-frozen, list-queue
+
+## v3.0.8 - 2016-04-01
+
+- Fix: pre- and post-install script failures no longer cause fatal exceptions, halting sync. Instead the error is reported, the package skipped, and the sync continues.
+
+## v3.0.7 - 2016-04-01
+
+Initial open source release
+
+## v3.0.6 - 2016-03-28
+
+Pixar internal release of v3.

data/README.md

@@ -4,8 +4,7 @@ d3 is a package deployment and patch management system for OS X that enhances th
 [Casper Suite](http://www.jamfsoftware.com/products/casper-suite/), an enterprise-level management system for Apple devices from [JAMF Software](http://www.jamfsoftware.com/). It was created by [Pixar Animation Studios](http://www.pixar.com/).
 
 
-
-d3 adds these, capabilities and more, to Casper's package handling:
+d3 adds these capabilities and more to Casper's package handling:
 
 * Automatic software updates on clients when new versions are released on the server
 * Pre-release piloting of new packages
@@ -15,21 +14,22 @@ d3 adds these, capabilities and more, to Casper's package handling:
 * Both the client and admin tools are command-line only and fully scriptable
 * Admin command-line options allow integration with developer workflows and package-retrieval tools
 
-d3 is written in Ruby and available as a rubygem called ['depot3'](https://rubygems.org/gems/depot3). It interfaces with Casper mostly via it's REST API using [ruby-jss](https://github.com/PixarAnimationStudios/ruby-jss), a ruby module that provides simple and powerful access to the API. It also uses Casper's backend MySQL database directly to provide enhanced features.
+d3 is written in Ruby and available as a rubygem called ['depot3'](https://rubygems.org/gems/depot3). It interfaces with Casper via its REST API using [ruby-jss](https://github.com/PixarAnimationStudios/ruby-jss), a ruby module that provides simple and powerful access to the API. It also uses Casper's backend MySQL database directly to provide enhanced features.
 
+## DOCUMENTATION
 
-Please see the [wiki](https://github.com/PixarAnimationStudios/depot3/wiki) for full documentation
+Full user/administrator documentation is available at the [GitHub project's wiki page](https://github.com/PixarAnimationStudios/depot3/wiki).
 
-The developer documentation for the D3 ruby module is at [http://www.rubydoc.info/gems/depot3](http://www.rubydoc.info/gems/depot3)
+The developer documentation for the D3 ruby module is at [http://www.rubydoc.info/gems/depot3](http://www.rubydoc.info/gems/depot3).
 
-Also check out [ruby-jss](https://github.com/PixarAnimationStudios/ruby-jss), which is used by d3, but is useful for working with the Casper REST API in any project. 
+Also check out [ruby-jss](https://github.com/PixarAnimationStudios/ruby-jss), which is used by d3, but is useful for working with the Casper REST API in any project.
 
 
 ## CONTACT
 
-[Email the developer](mailto:d3@pixar.com)
+[Email](mailto:d3@pixar.com)
 
-[Macadmins Slack Channel](https://macadmins.slack.com/messages/#d3/)
+[Macadmins Slack Channel](https://macadmins.slack.com/messages/#d3/)(@glenfarclas17)
 
 ## LICENSE
 
@@ -41,10 +41,7 @@ compliance with the Apache License and the following modification to it:
 
 Section 6. Trademarks. is deleted and replaced with:
 
-  6\. Trademarks. This License does not grant permission to use the trade
-  names, trademarks, service marks, or product names of the Licensor
-  and its affiliates, except as required to comply with Section 4(c) of
-  the License and to reproduce the content of the NOTICE file.
+> 6\. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor and its affiliates, except as required to comply with Section 4(c) of the License and to reproduce the content of the NOTICE file.
 
 You may obtain a copy of the Apache License at
 

data/bin/d3

@@ -59,6 +59,9 @@ class App
   # the following d3 commands need a connection to the server
   ACTIONS_NEEDING_SERVER = D3::Client::ACTIONS.select{|k,v| v[:needs_connection] }
 
+  # these actions can be done w/o being root, by default, actions need root
+  ACTIONS_OK_WO_ROOT = D3::Client::ACTIONS.select{|k,v| v[:needs_root] == false }
+
   ### set up
   ###
   def initialize(args)
@@ -89,7 +92,7 @@ class App
 
     # otherwise, yell if we need to be root.
     else
-      raise D3::PermissionError, "You must be root to use d3." unless [:help, :version].include? @action
+      raise D3::PermissionError, "You must be root to do that with d3." unless ACTIONS_OK_WO_ROOT.include? @action
     end #if root
 
     # bail if the jamf binary isn't installed
@@ -149,6 +152,9 @@ class App
   ###
   def parse_cli
 
+    # Debugging file? if so, always set debug.
+    ARGV << "--debug" if D3::DEBUG_FILE.exist?
+
     # when finished, this leaves the d3 command and its arg in ARGV
     opts = GetoptLong.new( *D3::Client::OPTIONS.values.map{|opt| opt[:cli]} )
 

data/bin/d3admin

@@ -1,5 +1,4 @@
 #!/usr/bin/ruby
-
 ### Copyright 2016 Pixar
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -135,6 +134,9 @@ class App
   ###
   def parse_commandline
 
+    # Debugging file? if so, always set debug.
+    ARGV << "--debug" if D3::DEBUG_FILE.exist?
+
     # this holds everything that comes from the commandline
     # or from prompting the user
     @options = OpenStruct.new
@@ -245,7 +247,7 @@ class App
           else
             raise ArgumentError, "--reboot must be 'y' or 'n'"
           end
-          
+
         when '--remove-first'
           # dft is no, so if arg is empty or /^n(o)$/i, it should be nil,
           # otherwise must be /^y(es)$/i
@@ -256,7 +258,7 @@ class App
           else
             raise ArgumentError, "--remove-first must be 'y' or 'n'"
           end
-          
+
         when '--removable'
           # dft is yes, so if arg is empty or /^y(es)$/i, it should be nil,
           # otherwise must be  /^n(o)$/i
@@ -267,7 +269,7 @@ class App
           else
             raise ArgumentError, "--removable must be 'y' or 'n'"
           end
-          
+
         when '--oses'
           @options.oses = arg
         when '--expiration'

data/bin/d3helper

@@ -72,7 +72,11 @@ class App
   ### and set up the infrasctructure. No actual processing/error checking
   ### until the run method is called.
   ###
-  def initialize(args)
+  def initialize
+
+    # Debugging file? if so, always set debug.
+    ARGV << "--debug" if D3::DEBUG_FILE.exist?
+
     opts = GetoptLong.new(
       [ '--help', '-h', '-H', GetoptLong::NO_ARGUMENT ],
       [ '--debug', '-d', GetoptLong::NO_ARGUMENT ],
@@ -275,18 +279,18 @@ Watch a parade of cute puppies while these items are installed:
     # this is an array of current d3 receipt ids
     d3_rcpt_ids =  D3::Client::Receipt.all.values.map{|r| r.id}
 
-    now = Time.now
-
     JSS::Client.receipts.each do |jss_rcpt|
 
 
-      # jss_rcpt is a Pathname object, the rcpt name is the paths basename
+      # jss_rcpt is a Pathname object, the rcpt name is the path's basename
       jss_rcpt_name = jss_rcpt.basename.to_s
 
       # do we have a match?
       pkg_id = d3_pkg_filenames[jss_rcpt_name]
-      # if not, the filename might end with .zip, but the rcpt name doesnt
+
+      # if not, the filename might end with .zip, but the rcpt name doesn't
       pkg_id ||= d3_pkg_filenames[jss_rcpt_name + ".zip"]
+
       # if still not, this jss recipt doesn't point to a d3 package.
       next unless pkg_id
 
@@ -297,6 +301,7 @@ Watch a parade of cute puppies while these items are installed:
       # If we're here, we need to import the receipt, so get the matching D3
       # package and make a receipt from it.
       D3.log "Importing Casper Receipt #{jss_rcpt_name}", :warn
+
       begin
         d3_pkg = D3::Package.new id: pkg_id
 
@@ -312,11 +317,11 @@ Watch a parade of cute puppies while these items are installed:
           :basename =>  d3_pkg.basename,
           :version =>  d3_pkg.version,
           :revision =>  d3_pkg.revision,
-          :admin =>  D3::AUTO_INSTALL_ADMIN,
+          :admin =>  "imported-from-casper",
           :id =>  d3_pkg.id,
           :status =>  d3_pkg.status ,
           :jamf_rcpt_file =>  jss_rcpt,
-          :apple_pkg_ids =>  nil,
+          :apple_pkg_ids =>  d3_pkg.apple_receipt_data.map{|rd| rd[:apple_pkg_id]},
           :installed_at =>  jss_rcpt.mtime,
           :removable =>  d3_pkg.removable,
           :expiration => d3_pkg.expiration,
@@ -326,14 +331,15 @@ Watch a parade of cute puppies while these items are installed:
           :post_remove_script_id => d3_pkg.post_remove_script_id
         )
         D3::Client::Receipt.add_receipt d3_rcpt, :replace
-        D3.log "Done. Imported Casper Receipt #{jss_rcpt_name}", :warn
       rescue
         D3.log "ERROR importing Casper Receipt #{jss_rcpt_name}: #{$!}", :error
       end
 
-      D3.log "Done importing Casper Receipts for packages in d3", :warn
 
     end #JSS::Client.receipts.each do |jss_rcpt|
+    D3.log "Done importing Casper Receipts for packages in d3", :warn
+
+
   end #import_receipts
 
 end # class App
@@ -344,7 +350,7 @@ end # class App
 ############
 begin
   app = nil
-  app = App.new(ARGV)
+  app = App.new
   app.run
   exit 0
 rescue

data/lib/d3/admin/add.rb

@@ -22,9 +22,13 @@
 ###
 ###
 
-
+###
 module D3
   module Admin
+
+    ### The Admin::Add modile contains constants and methods related to
+    ### adding packages to d3 via d3admin.
+    ###
     module Add
       extend self
 

data/lib/d3/admin/auth.rb

@@ -22,7 +22,7 @@
 ###
 ###
 
-
+###
 module D3
   module Admin
 

data/lib/d3/admin/edit.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
   module Admin
     module Edit

data/lib/d3/admin/help.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
   module Admin
     # This just exists to get the very lengthy help texts out of the d3admin and

data/lib/d3/admin/interactive.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
   module Admin
 

data/lib/d3/admin/options.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
   module Admin
 

data/lib/d3/admin/prefs.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
 
   module Admin

data/lib/d3/admin/report.rb

@@ -22,6 +22,9 @@
 ###
 ###
 
+
+
+###
 module D3
   module Admin
     module Report

data/lib/d3/admin/state.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
 
   module Admin

data/lib/d3/admin/validate.rb

@@ -22,6 +22,7 @@
 ###
 ###
 
+###
 module D3
   module Admin
 

data/lib/d3/admin.rb

@@ -23,8 +23,12 @@
 ###
 
 
-
+###
 module D3
+
+  ### D3::Admin provides the inner-workings of the d3admin command.
+  ### See the various submodules, and d3admin itself, for details.
+  ###
   module Admin
 
   end # module Admin
@@ -40,3 +44,4 @@ require "d3/admin/options"
 require "d3/admin/prefs"
 require "d3/admin/report"
 require "d3/admin/validate"
+

data/lib/d3/basename.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
 
   ###

data/lib/d3/client/auth.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
 
   class Client < JSS::Client

data/lib/d3/client/class_methods.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
   class Client < JSS::Client
 
@@ -75,11 +76,16 @@ module D3
           end # unless options.force
 
           if curr_rcpt
-            D3.log("Un-freezing #{curr_rcpt.edition} by installing #{desired_pkg.edition} manually", :warn) if curr_rcpt.frozen?
-            D3.log("Updating #{curr_rcpt.edition}(#{curr_rcpt.status}) by installing #{desired_pkg.edition} manually", :warn) unless  curr_rcpt.live?
-          end # if curr rcpt
+            D3.log("Un-freezing #{curr_rcpt.edition} by installing #{desired_pkg.edition}", :warn) if curr_rcpt.frozen?
 
-          installing = desired_pkg.live? ? "currently live #{desired_pkg.basename}" : "#{desired_pkg.edition} (#{desired_pkg.status})"
+            if  desired_pkg.id == curr_rcpt.id
+              D3.log("Re-installing #{desired_pkg.edition}(#{desired_pkg.status})", :warn)
+            elsif  desired_pkg.id < curr_rcpt.id
+              D3.log("Rolling back #{curr_rcpt.edition}(#{curr_rcpt.status}) to #{desired_pkg.edition}(#{desired_pkg.status})", :warn)
+            else
+              D3.log("Updating #{curr_rcpt.edition}(#{curr_rcpt.status}) to #{desired_pkg.edition}(#{desired_pkg.status})", :warn)
+            end
+          end # if curr rcpt
 
           desired_pkg.install(
             :force => options.force,
@@ -92,7 +98,7 @@ module D3
 
           self.freeze_receipts([desired_pkg.basename]) if options.freeze_on_install
 
-          D3.log "Finished installing #{installing}", :info
+          D3.log "Finished installing #{desired_pkg.edition}(#{desired_pkg.status})", :info
 
         rescue JSS::MissingDataError, JSS::NoSuchItemError, JSS::InvalidDataError, D3::InstallError
           D3.log "Skipping installation of #{pkg_to_search}:\n   #{$!}", :error

data/lib/d3/client/class_variables.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
   class Client < JSS::Client
 

data/lib/d3/client/cli.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
   class Client < JSS::Client
 
@@ -74,22 +75,27 @@ module D3
         list_installed: {
           :aka => :li,
           :help => "list all installed d3 pkgs on this machine",
+          :needs_root => false
         },
         list_manual: {
           :aka => :lm,
           :help => "list all d3 pkgs on this machine not auto-installed",
+          :needs_root => false
         },
         list_pilots: {
           :aka => :lp,
           :help => "list pkgs currently in pilot on this machine",
+          :needs_root => false
         },
         list_frozen: {
           :aka => :lf,
           :help => "list pkgs currently frozen on this machine",
+          :needs_root => false
         },
         list_puppies: {
           :aka => :lq,
           :help => "list any queued pkgs awaiting puppytime at logout",
+          :needs_root => false
         },
         list_details: {
           :aka => :ld,
@@ -100,7 +106,7 @@ module D3
         list_files: {
           :aka => :ls,
           :help => "list the files installed by the given editions",
-          :arg => :"basename or edition",
+          :arg => :"basename or edition" ,
           :needs_connection => true
         },
         query_file: {

data/lib/d3/client/environment.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
 
   class Client < JSS::Client

data/lib/d3/client/help.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
   class Client < JSS::Client
     module Help

data/lib/d3/client/lists.rb

@@ -23,12 +23,17 @@
 ###
 
 
-### client/lists.rb
-###
-### Methods related to the display of lists via the d3 client tool
-###
 
+
+###
 module D3
+
+  ### client/lists.rb
+  ###
+  ### Methods related to the display of lists via the d3 client tool
+  ###
+
+
   class Client < JSS::Client
 
     ### list installed d3 items.

data/lib/d3/client/receipt.rb

@@ -22,6 +22,9 @@
 ###
 ###
 
+
+
+###
 module D3
   class Client < JSS::Client
 
@@ -288,9 +291,10 @@ module D3
             end # if
           end # unless replace
 
+          replacing = @@installed_rcpts[receipt.basename] ? true : false
           @@installed_rcpts[receipt.basename] = receipt
           self.save_receipts
-          D3.log "#{replace ? "Replaced" : "Added"} receipt for #{receipt.edition}", :info
+          D3.log "#{replacing ? "Replaced" : "Added"} receipt for #{receipt.edition}", :info
 
         ensure
           # always release the rw lock even after an error

data/lib/d3/client.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
 
   ### This class represents a d3 client, a computer managed

data/lib/d3/configuration.rb

@@ -22,6 +22,7 @@
 ###
 ###
 
+
 ###
 module D3
 

data/lib/d3/constants.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
 
   #####################################
@@ -57,4 +58,9 @@ module D3
   # reports can take a long time to generate, lets set the timeout to a long time.
   REPORT_CONNECTION_TIMEOUT = 3600
 
+  # when this file exists, d3, d3admin are set to debug mode. This is
+  # useful when you have a d3 command embedded in some other tool, but need to get
+  # debug logging.
+  DEBUG_FILE = Pathname.new "/tmp/d3debug-on"
+
 end # module

data/lib/d3/database.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
 
   module Database

data/lib/d3/exceptions.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
 
   class InstallError < RuntimeError ; end

data/lib/d3/log.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
 
   ### Log a message to the d3 log, possibly sending it to stderr as well.

data/lib/d3/package/aliases.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
   class Package < JSS::Package
 

data/lib/d3/package/attributes.rb

@@ -23,8 +23,11 @@
 ###
 
 
+###
 module D3
+
   class Package < JSS::Package
+
         ################# Instance Attributes #################
 
     ### Note - I was tempted to set these up programmatically

data/lib/d3/package/class_methods.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
   class Package < JSS::Package
 
@@ -207,7 +208,7 @@ module D3
       @@filenames = nil if refresh
       return @@filenames if @@filenames
       @@filenames = {}
-      qr = JSS::DB_CNX.db.query "SELECT package_id, file_name FROM packages"
+      qr = JSS::DB_CNX.db.query "SELECT package_id, file_name FROM packages WHERE package_id IN (SELECT package_id FROM #{D3::Package::P_TABLE[:table_name]})"
       qr.each_hash{|p| @@filenames[p["package_id"].to_i] =  p["file_name"]}
       qr.free
       @@filenames

data/lib/d3/package/class_variables.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
   class Package < JSS::Package
 

data/lib/d3/package/client_actions.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
   class Package < JSS::Package
 

data/lib/d3/package/constants.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
   class Package < JSS::Package
 

data/lib/d3/package/constructor.rb

@@ -23,8 +23,10 @@
 ###
 
 
+###
 module D3
   class Package < JSS::Package
+
     ################# Constructor #################
 
     ###  Existing d3 pkgs are looked up by providing :id, :name,

data/lib/d3/package/getters.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
   class Package < JSS::Package
 

data/lib/d3/package/mixins.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
   class Package < JSS::Package
 

data/lib/d3/package/private_methods.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
   class Package < JSS::Package
 

data/lib/d3/package/questions.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
   class Package < JSS::Package
 

data/lib/d3/package/server_actions.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
   class Package < JSS::Package
 

data/lib/d3/package/setters.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
   class Package < JSS::Package
 

data/lib/d3/package/validate.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
   class Package < JSS::Package
 
@@ -65,7 +66,7 @@ module D3
     ###
     def check_for_exclusions
       excl_grps = D3::Client.computer_groups & @excluded_groups
-      raise D3::InstallError,  "This machine is excluded for #{desired_pkg.edition}. Use --force if needed." unless excl_grps.empty?
+      raise D3::InstallError,  "This machine is excluded for #{edition}. Use --force if needed." unless excl_grps.empty?
       return true
     end # check for exclusions
 

data/lib/d3/package.rb

@@ -22,9 +22,11 @@
 ###
 ###
 
+
+
+###
 module D3
 
-  ###
   ### Package - A JSS::Package that can be installed and maintained by d3
   ###
   class Package < JSS::Package

data/lib/d3/puppytime/pending_puppy.rb

@@ -23,22 +23,14 @@
 ###
 
 
+###
 module D3
+
   module PuppyTime
 
     ###
     ### PendingPuppy - a d3 pkg awaiting installation during puppytime.
     ###
-    ### We don't need much data about the pkg to be installed
-    ### These are required in the args:
-    ###    :basename
-    ###    :version
-    ###    :revision
-    ###    :admin
-    ###    :status
-    ### These are optional:
-    ###    :force - use force when installing
-    ###
     class PendingPuppy
 
       ################# Mixin Modules #################
@@ -60,8 +52,15 @@ module D3
 
       ################# Constructor #################
 
-      ###
-      ###
+      ### We don't need much data about the pkg to be installed
+      ### These are required in the args:
+      ###    :basename
+      ###    :version
+      ###    :revision
+      ###    :admin
+      ###    :status
+      ### These are optional:
+      ###    :force - use force when installing
       ###
       def initialize (args = {})
         raise JSS::MissingDataError, "Puppies need a :basename" unless args[:basename]
@@ -85,6 +84,9 @@ module D3
       end # init
 
       ### Install this puppy
+      ###
+      ### @return [void]
+      ###
       def install
 
         begin # for ensure
@@ -101,8 +103,6 @@ module D3
         end
       end # install
 
-
-
     end #class PendingPuppy
   end # module puppytime
 end #module D3

data/lib/d3/puppytime/puppy_queue.rb

@@ -23,9 +23,12 @@
 ###
 
 
+###
 module D3
   module PuppyTime
+
       ### PuppyQ - the current queue of pending puppy installs.
+      ###
       ### This class only has one real value: A hash of
       ### PendingPuppy objects, keyed by basename.
       ### But, PendingPuppies can be added and removed
@@ -45,6 +48,7 @@ module D3
 
         ################# Class Methods #################
 
+
         ################# Attributes #################
 
         # the queue of PendingPuppy objects
@@ -77,11 +81,13 @@ module D3
 
         ### Save the current q out to disk
         ###
+        ### @return [void]
+        ###
         def save_q
           D3.log "Saving puppy queue", :debug
           if @q.empty?
             D3.log "Puppy queue is empty, deleting from disk", :debug
-            QUEUE_FILE.delete
+            QUEUE_FILE.delete if QUEUE_FILE.exist?
           else
             QUEUE_FILE.jss_save YAML.dump(@q)
             D3.log "Puppy queue saved to disk", :debug
@@ -89,6 +95,8 @@ module D3
 
         end # save_q
 
+        ### An array of basenames for all pending puppies.
+        ###
         ### @return [Array<String>] the basenames of the pending puppies
         ###
         def pups

data/lib/d3/puppytime.rb

@@ -25,13 +25,12 @@
 require 'd3/puppytime/pending_puppy'
 require 'd3/puppytime/puppy_queue'
 
-
-
+###
 module D3
 
-  # Constants and methods for PuppyTime, which installs the pkgs listed in the
-  # PuppyQueue at logout.
-  #
+  ### Constants and methods for PuppyTime, which installs the pkgs listed in the
+  ### PuppyQueue at logout.
+  ###
   module PuppyTime
 
     ################# Module Constants #################

data/lib/d3/state.rb

@@ -23,22 +23,25 @@
 ###
 
 
+###
 module D3
 
-  # this will be set to true when we finish loading
-  @@loaded = false
-
+  ### is the module fully loaded?
+  ###
+  ### @return [Boolean]
+  ###
   def self.loaded?
     @@loaded
   end
 
-  # This stores the current level of log messages
-  # sent to stdout. See
-  # D3::Log.level to set the level for messages
-  # sent to the log.
-  # @return [Integer]
+  ### This stores the current level of log messages sent to stdout. See
+  ### D3::Log.level to set the level for messages sent to the log.
+  ###
   @@verbosity = D3::Log::DFT_VERBOSITY
 
+  ### The current verbosity level
+  ### @return [Integer]
+  ###
   def self.verbosity
     @@verbosity
   end
@@ -63,23 +66,35 @@ module D3
   end
 
 
-  # have we been asked to be forceful, and perform
-  # unnatural acts?
-  # Force is used in many different was in many places
-  # so we'll store it here and anything can access it
-  # using D3::force, D3::unforce, and D3::forced?
+  ### Have we been asked to be forceful, and perform
+  ### unnatural acts?
+  ### Force is used in many different was in many places
+  ### so we'll store it here and anything can access it
+  ### using D3::force, D3::unforce, and D3::forced?
   @@force = false
 
+  ### Turn on force, module-wide
+  ###
+  ### @return [void]
+  ###
   def self.force
     @@force = true
     D3::Client.set_env :force
   end
 
+  ### Turn off force, module-wide
+  ###
+  ### @return [void]
+  ###
   def self.unforce
     @@force = false
     D3::Client.unset_env :force
   end
 
+  ### Is force turned on, module-wide?
+  ###
+  ### @return [Boolean]
+  ###
   def self.forced?
     @@force
   end
@@ -95,6 +110,7 @@ module D3
   ###   what hosts and usernames
   ###
   def self.connected?
+    return false unless loaded?
     return false unless JSS::API.connected? and JSS::DB_CNX.connected?
     return {
       :api => (JSS::API.cnx.options[:user] + "@" + JSS::API.cnx.options[:server]),

data/lib/d3/utility.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
 
 
@@ -37,10 +38,11 @@ module D3
     return false
   end #
 
-  ### Try to figure out the login name of the admin
-  ### running this code
+  ### Try to figure out the login name of the admin running this code
+  ###
+  ### @return [String] an admin name.
   ###
-  def self.admin (refresh = false)
+  def self.admin
 
     no_good = self.badmins
 
@@ -59,8 +61,7 @@ module D3
     return admin
   end # get admin name
 
-  ### The list of names not allowed as the --admin option in
-  ### d3 and d3admin
+  ### The list of names not allowed as the --admin option in d3
   ###
   ### This just combines DISALLOWED_ADMINS and
   ### D3::CONFIG.client_prohibited_admin_names
@@ -83,15 +84,19 @@ module D3
   ### @return [boolean] Did the policy run?
   ###
   def self.run_policy (policy, type, verbose = false)
+
     D3.log "Running #{type} policy", :info
+
     # if numeric, and there's a policy with that id
     if policy =~ /^\d+$/ and polname = JSS::Policy.map_all_ids_to(:name)[policy]
       D3.log "Executing #{type} policy '#{polname}', id: #{policy}", :debug
       pol_to_run = "-id #{policy}"
+
     # if there's a policy with that name
     elsif polid = JSS::Policy.map_all_ids_to(:name).invert[policy]
       D3.log "Executing #{type} policy '#{policy}', id: #{polid}", :debug
       pol_to_run = "-id #{polid}"
+
     # else assume its a trigger
     else
       D3.log "Executing #{type} policy with trigger '#{policy}'", :debug
@@ -115,6 +120,7 @@ module D3
 
   ### Get the ids of all scripts used by all policies
   ### This is a hash of PolicyName => Array of Script id's
+  ###
   ### @return [Hash{String => Array<Integer>}]
   ###
   def self.policy_scripts
@@ -272,7 +278,7 @@ module D3
   ### This enhances Plist::parse_xml taking file paths, as well as XML Strings
   ### and reading the files regardless of binary/XML format.
   ###
-  ### see JSS::parse_plsit
+  ### see JSS::parse_plist
   ### TODO - make all calls to this go directly to JSS.parse_plist
   ###
   ### @param plist[Pathname, String] the plist XML, or the path to a plist file

data/lib/d3/version.rb

@@ -23,6 +23,7 @@
 ###
 
 
+###
 module D3
-  VERSION = '3.0.8'
+  VERSION = '3.0.9'
 end # module

data/lib/d3.rb

@@ -19,16 +19,24 @@
 ###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 ###    KIND, either express or implied. See the Apache License for the specific
 ###    language governing permissions and limitations under the Apache License.
-###
-###
+
+
+
+### The D3 module provides the foundation, and the guts, of d3. Most of the work
+### of the executables (d3, d3admin, d3helper, puppytime) is performed here. It
+### in turn, is built upon the JSS module, provided by the ruby-jss gem, for API
+### and MySQL access to the JSS.
+module D3
+  # Set to true after all files are required
+  @@loaded = false
+end
 
 #####################################
 # Required Libraries, etc
 #####################################
 
 ###################
-# gems
-
+# Gems
 require 'jss'
 require 'keychain'
 
@@ -66,14 +74,10 @@ require 'd3/client'
 require 'd3/puppytime'
 
 
+###
 module D3
-
-  ### we're loaded!
   @@loaded = true
-
-  # Start logging
   D3.log "D3 module loaded, logging started", :debug
-
 end # module D3
 
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: depot3
 version: !ruby/object:Gem::Version
-  version: 3.0.8
+  version: 3.0.9
 platform: ruby
 authors:
 - Chris Lasell
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-04-02 00:00:00.000000000 Z
+date: 2016-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-keychain