Release plist and macos_user resources, new Xcode libraries, test cookbook and documentation. (#24)

* first commit plistbuddy

* all recipe/plist in macos

* extract plistbuddy to resource

* Straighten out unit tests

- Correctly include modules
- Correctly setup spec_helper
- Correct unit test / respec setup

* first passing test

* add more data type tests

* Most data types passing

- Boolean values are working
- Array and data type values are not
- PlistBuddy "commands" (add, print, etc.) are passing

* More testing

- Skip Array and Dict types as their implementation will be more
complicated
- Add test for float type
- Put the correct type in the test description
- Cookstyle changes

* PlistBuddy and testing update

- Add separate test cookbook for PlistBuddy resource
- Add kitchen.yml for the above purpose
- Modify and update plistbuddy resource/helpers

* remove extra newline

* add metadata file

* edit metadata; add Berksfile

* move Berksfile to correct location

* add testing requirements for berks vendor

* move kitchen file

* Converge passing in test cookbook

- Opportunistic cleanup of xcode test
- some temp debugging info in resource definition
- Rename name_property to command so as to not override action

* Itempotence

- Removed 'bool' prefix from boolean types, as that was somehow causing
issues
- Changed name_property to the path and removed that property
- Use actual actions in the resource for the PlistBuddy commands

* Fix false positive?

- Not sure how the previous test was passing previously, but I adjusted
the boolean value for the BazEntry test so that the signature input
matches the output

* Add logic for adding a value

- The data type should only be used when adding a value to a plist.
Otherwise, we don't need to use the data type

* remove debugging; fix smoke tests

* remove .kitchen.yml

* bump version to 0.8.5

* unskip ChefSpec tests - they're passing

* mark args_formatter as private method

* Feature/macos user (#14)

* first commit add_user recipe

* Testing Refactor & macos_user resource

- Create new testing cookbook that contains tests for both plistbuddy
and macos_user resources. The hope here is to have a single testing
cookbook that contains multiple suites and suite testing variations
- Create new macos_user resource - contains single boolean 'true'
settings for autologin and admin user. Still work to be done for admin
user and all steps that need to be taken to acheive the task.

* fix method call

* fix another method call

* user native ruby File class and not overriden

* fix some minor issues with resource; add kcpassword file

* Add OG Ruby kcpassword file helper module

* slightly different approach for Kcpassword module

* passing test

* Fix up kcpassword library module, smoke tests

- Modify Kcpassword helper module to use a method for
magic bits. This isn't ideal, but it works for now
- Update smoke tests so that john_jr's group ID is 20. This
may not be correct, but setting as 20 until it is further
investigated

* opportunistic refactor of keep_awake recipe

* Refactor testing cookbook layout

- Consolodate testing suites into single default suite
- Add tests for keep_awake recipe
- Use more common examples to test PlistBuddy resource

* move xcode test to test cookbook

* Opportunistic bug fix for plistbuddy resource

- Previously, the plistbuddy resource did not allow
any keys with spaces unless they were used in the value itself.
Now, you can use keys with spaces in the value property
without needing to double-quote it
- Also, fix the PlistBuddy executable string to be correct

* revert kcpassword.rb helper to a671164

* fix incorrect PlistBuddy data type name

* Fix kcpassword.rb and update plistbuddy UTs

* Extract disabling screen saver to plistbuddy

- Also, skip Xcode test temporarily

* PlistBuddy idempotence

- Remove systemsetup and pmset resource calls in keep_awake
until they are made idempotent

* update test and plist name

* Implement binary plist conversion

- Changes to binary plists via PlistBuddy must be converted back
to binary since the change implicitly converts the file to xml.
This change contains logic to convert back to binary if the file is
detected to be binary in the first place.

* attempts at idempotence using chef helper methods

* early commit to get it on the remote

* implement logic for plist return type to ruby data type

* Add floating type value support

A wild FAILING TEST appeared!
...
HANKO used TDD!
It's super effective!

* move function

* real idempotence!

* passing all unit tests

* update test cookbook name

* update new_users integration tests

* systemsetup idempotence

* all smoke and unit tests passing

* quick fix for timezone bug

* remove kcpassword file as it is no longer needed

* update path for test cookbook to be default repo name

* Rename keep_awake_spec.rb to keep_awake_test.rb

* Rename preferences_spec.rb to preferences_test.rb

* Rename new_users_spec.rb to new_users_test.rb

* fix typo

* Use relative path for macos cookbook source

* Improve readability of relative path for macos cookbook source

* Bump version

* Addressing changes in Pull Request #14

- Fix bug where screensaver was not properly being disabled, update
tests accordingly
- Rename plistbuddy resource to plist, including all related files
and callers
- Rename kcpassword helper to macos_user to match helper -> resource
convention; fix top level namespace to be MacOS
- Correctly name recipe unit tests
- Implement plist resource into disable_software_updates.rb recipe
- Add disable_software_updates.rb recipe to default kitchen suite and
appropriate smoke tests
- Remove relatively useless logic in systemsetup value property coercion

* Implement binary plist conversion

* Fix unit test and apply the Law of Demeter

* update helper pattern to match current standard; include everywhere

* remove helper reference in Xcode resource

* bump version

* update Xcode attribute to latest

* extract xcode smoke tests to a different suite

* update xcversion path for simulators test

* update namespace again

* refactor XcodeHelper modules in XCVersion, Xcode, and XCVersion modules

updated methods to simplify site calls in resource

* updated method calls for new modules

* bump version

* extract xcversion module to separate library file

* add missing macos module

* include parent module macos instead of child for xcode and xcversion

* update available_simulator_versions to new method

* bump version

* add platform-specific smoke test for xcode

* add xcode test recipe

* update kitchen with xcode suite

* refactor simulator method to call it's own available list of simulators

* use new simulator method to find highest available version

* move xcode prep work into the setup action

* clear kitchen customizations

* lazily evalutate ios simulator property

* move lazy evaluation to simulator action in xcode resource

* revert lazy execution

* warn and retry if simulator list is empty

* restore spacing

* more whitespace

* refactor highest_semantic_simulator method into class, smaller methods

* implement simulator class

* add more xcversion command methods

* implement xcversion command methods

* implement command methods correctly

* add list methods for xcversion

* implement xcversion list methods

* implement install xcode correctly

* reorder methods

* add method to list installed xcodes

* use more descriptive name for 'command' method

* move where the space lives

* implement installed xcodes command

* implement install xcodes correctly

* disable downloads prior to disabling software update check

* Renamed name to device_name

* Change name.rb to machine_name.rb to be similar with the apex
automation cookbook. Instances of name are also all changed to
machine_name.

* Add new test recipe and smoke test for machine_name.

* add disable-swu test suite

* Bump up cookbook version numbers.

* update kitchen test suite order, remove standalone swu testing

* add sleep for El Capitan platform to avoid race condition

this occurs when integrated with the macos-user test recipe

* Improve README/Documentation (#23)

* implement build definition badge and minor tweaks

* Add descriptions and attribute lists for recipes

* Remove 'description' label from recipe names

* Bump version, add documentation dir

* Fix up the last commit

* Separate 10.12 and 10.13 build status

* Add table for build status

* Add plist resource documentation

* Add Xcode documentation

* bump version

Author: jazaval

.gitignore

@@ -68,6 +68,7 @@ kitchen-tests/vendor
 
 # Visual Studio Code files
 .vscode
+*/**/*.code-workspace
 # Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio and Webstorm
 .idea
 
@@ -101,3 +102,4 @@ Vagrantfile
 .rubocop.yml
 .vagrant
 data_bags
+*.code-workspace

README.md

@@ -1,18 +1,31 @@
-# macOS Cookbook
+macOS Cookbook
+==============
 
-This cookbook provides:
-- Resources for configuring and provisioning macOS.
-- Recipes that implement common use-cases of the macOS cookbook's recources.
+The macOS cookbook is a Chef library cookbook that provides resources for configuring
+and provisioning macOS. Additionally, it provides recipes that implement common
+use-cases of the macOS cookbook's recources.
 
-## Platforms
+|||
+|-|-|
+| macOS Sierra 10.12 | ![build-status-1012](https://office.visualstudio.com/_apis/public/build/definitions/59d72877-1cea-4eb6-9d06-66716573631a/2143/badge) |
+| macOS High Sierra 10.13 | ![build-status-1013](https://office.visualstudio.com/_apis/public/build/definitions/59d72877-1cea-4eb6-9d06-66716573631a/2140/badge) |
+|||
 
-- macOS
+Requirements
+------------
 
-## Chef
+- Only tested on Chef 13
+- Surprisingly, this cookbook is only compatible with macOS
 
-- Chef 13+
+Supported OS Versions
+---------------------
 
-## Attributes
+- OS X El Capitan 10.11
+- macOS Sierra 10.12
+- macOS High Sierra 10.13
+
+Attributes
+----------
 
 ### Admin User and Password
 
@@ -22,33 +35,89 @@ node['macos']['admin_password'] = 'vagrant'
 ```
 
 Each of these attributes defaults to vagrant since our resources are developed
-with the Vagrant paradigm. In other words, the use and password declared here
-should be an admin user.
+with the Vagrant paradigm. In other words, the user and password declared here
+should be an admin user with passwordless super-user rights.
+
+Recipes
+-------
+
+### Disable Software Updates
+
+Disables automatic checking and downloading of software updates.
+
+**Usage:** `include_recipe macos::disable_software_updates`
+
+No attributes used in this recipe.
+
+### Keep Awake
+
+Prevent macOS from falling asleep, disable the screensaver, and
+several other settings to always keep macOS on. Uses the `plistbuddy` and `pmset`
+resources.
+
+**Usage:** `include_recipe macos::keep_awake`
+
+| Attribute used                        | Default value           |
+|---------------------------------------|-------------------------|
+| `node['macos']['network_time_server']`| `'time.windows.com'`    |
+| `node['macos']['time_zone']`          | `'America/Los_Angeles'` |
 
 ### Mono
 
-_TODO_
+Installs [Mono](http://www.mono-project.com/docs/about-mono/). Requires package
+name, version number, and checksum in order to override.
 
----
+**Usage:** `include_recipe macos::mono`
 
-## Resources
+| Attribute used                      | Default value              |
+|-------------------------------------|----------------------------------------|
+| `node['macos']['mono']['package']`  | `'MonoFramework-MDK-4.4.2.11.macos10.xamarin.universal.pkg'` |
+| `node['macos']['mono']['version']`  | `'4.4.2'`                  |
+| `node['macos']['mono']['checksum']` | `'d8bfbee7ae4d0d1facaf0ddfb70c0de4b1a3d94bb1b4c38e8fa4884539f54e23'` |
 
-- `ard`
-- `name`
-- `defaults`
-- `pmset`
-- `systemsetup`
-- `xcode`
+### Xcode
 
-Checkout the [Wiki](https://github.com/Microsoft/macos-cookbook/wiki) for details about the macOS Cookbook resources.
+Installs Xcode 9.1 and simulators for iOS 10 and iOS 11. Check out
+the documentation for the Xcode resource if you need more flexibility.
 
----
+:large_orange_diamond: Requires an `apple_id` data bag item.
 
-## Recipes
+**Usage:** `include_recipe macos::xcode`
 
-- `disable_software_updates`
-- `keep_awake`
-- `mono`
-- `configurator`
+| Attribute Used                                                | Default value |
+|---------------------------------------------------------------|---------------|
+| `node['macos']['xcode']['version']`                           |  `'9.1'`      |
+| `node['macos']['xcode']['simulator']['major_version']`        | `%w(11 10)`   |
+
+### Apple Configurator 2
+
+Installs Apple Configurator 2 using `mas` and links `cfgutil` to
+`/usr/local/bin`.
+
+:large_orange_diamond: Requires an `apple_id` data bag item.
+
+**Usage:** `include_recipe macos::configurator`
+
+**Attributes**: No attributes used in this recipe.
+
+#### Data Bags
+
+Both the `macos::xcode` and `macos::configurator` recipes require a data bag
+item named `apple_id` containing valid Apple ID credentials. For example:
+
+**Example:**
+
+```json
+{
+  "id": "apple_id",
+  "apple_id": "[email protected]",
+  "password": "0k@yN0cR34m"
+}
+```
 
+Resources
+---------
 
+- [ARD (Apple Remote Desktop)](./documentation/resource_ard.md)
+- [Plist](./documentation/resource_plist.md)
+- [Xcode](./documentation/resource_xcode.md)

attributes/default.rb

@@ -5,5 +5,8 @@
 default['macos']['mono']['version'] = '4.4.2'
 default['macos']['mono']['checksum'] = 'd8bfbee7ae4d0d1facaf0ddfb70c0de4b1a3d94bb1b4c38e8fa4884539f54e23'
 
-default['macos']['xcode']['version'] = '9.0'
+default['macos']['xcode']['version'] = '9.1'
 default['macos']['xcode']['simulator']['major_version'] = %w(11 10)
+
+default['macos']['network_time_server'] = 'time.windows.com'
+default['macos']['time_zone'] = 'America/Los_Angeles'

documentation/resource_ard.md

@@ -0,0 +1,133 @@
+ard
+===
+
+Use the **ard** resource to manage Remote Desktop settings and preferences.
+Under the hood, an **ard** resource executes the `kickstart` command, located
+in ARDAgent.app (one of the CoreServices of macOS). It has some basic actions,
+which pertain to the simple `kickstart` subcommands. It also has the more
+complicated `:configure` action, which requires some familiarity with
+`kickstart`.
+
+[Learn more about the `kickstart` command](https://support.apple.com/en-us/HT201710).
+
+Syntax
+------
+
+A **ard** resource block declares a basic description of the command configuration
+and a set of properties depending on the actions executed. For example:
+
+```ruby
+ard 'activate and configure ard' do
+  action [:activate, :configure]
+end
+```
+
+where
+
+- `:activate` activates the ARD agent
+- `:configure` configures the agent using the `kickstart` defaut commandline arguments.
+
+The full syntax for all of the properties that are available to the **ard**
+resource is:
+
+```ruby
+ard 'description' do
+  install_package                      String
+  uninstall_options                    Array,  # defaults to ['-files', '-settings', '-prefs'] if not specified
+  restart_options                      Array, # defaults to ['-agent', '-console', '-menu'] if not specified
+  users                                Array
+  privs                                Array, # defaults to ['-all'] if not specified
+  access                               String, # defaults to '-on' if not specified
+  allow_access_for                     String, # defaults to '-allUsers' if not specified
+  computerinfo                         Array
+  clientopts                           Array
+  action                               Symbol # defaults to [:activate, :configure] if not specified
+end
+```
+
+**Note:** Not all properties are compatible with each action.
+
+Actions
+-------
+
+This resource has the following actions:
+
+`:activate`
+
+      Activate the remote desktop agent.
+
+`:deactivate`
+
+      Deactivate the remote desktop agent.
+
+`:uninstall`
+
+      Uninstall a package from another remotely
+managed mac.
+
+`:stop`
+
+      Stop the agent.
+
+`:restart`
+
+      Restart the remote desktop agent.
+
+`:configure`
+
+      Configure the setup of the remote desktop
+agent using the default options. If you were to configure the default options,
+your settings would look like this in the GUI:
+
+Properties
+----------
+
+`install_package`
+
+      **Ruby Type:** `String`
+
+`uninstall_options`
+
+      **Ruby type:** `Array`
+
+      default options: `['-files', '-settings', '-prefs']`
+
+`restart_options`
+
+      **Ruby type:** `Array`
+
+      default options: `['-agent', '-console', '-menu']`
+
+`users`
+
+      **Ruby type:** `Array`
+
+`privs`
+
+      **Ruby type:** `Array`
+
+      default: `['-all']`
+
+`access`
+
+      **Ruby type:** `String`
+
+      default: `'-on'`
+
+`allow_access_for`
+
+      **Ruby type:** `String`
+
+      default: `'-allUsers'`
+
+`computerinfo`
+
+      **Ruby type:** `Array`
+
+`clientopts`
+
+      **Ruby type:** `Array`
+
+`action`
+
+      **Ruby type:** `Symbol`

documentation/resource_plist.md

@@ -0,0 +1,64 @@
+plist
+=====
+
+Use the **plist** resource to manage property list files (plists) and their content.
+A **plist** resource instance represents the state of a single key-value pair in
+the delared plist `path`. Since each plist resource instance represents only one
+setting, you may end up with several plist resource calls in a given recipe. Although
+this may seem like overkill, it allows us to have a fully idempotent resource with
+fine granularity.
+
+During the `chef-client` run, the client knows to check the state of the plist
+before changing any values. It also makes sure that the plist is in binary format
+so that the settings can be interpreted correctly by the operating system.
+
+Prior knowledge of using commandline utilities such as `/usr/bin/defaults`
+and `/usr/libexec/PlistBuddy` will be useful when implementing the
+**plist** resource.
+
+[Learn more about property lists.](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/PropertyLists/QuickStartPlist/QuickStartPlist.html#//apple_ref/doc/uid/10000048i-CH4-SW5)
+
+Syntax
+------
+
+The full syntax for all of the properties that are available to the **plist**
+resource is:
+
+```ruby
+plist 'description' do
+  path                                 String # defaults to 'description' if not specified
+  entry                                String
+  value                                TrueClass, FalseClass, String, Integer, Float 
+  action                               Symbol # defaults to :set if not specified
+end
+```
+
+Actions
+-------
+
+This resource has the following actions:
+
+`:set`
+
+      Set `entry` to `value` in `path`
+
+Examples
+--------
+
+Enabling the setting to show both visible and invisible files.
+
+```ruby
+plist 'show hidden files' do
+  path '/Users/vagrant/Library/Preferences/com.apple.finder.plist'
+  entry 'AppleShowAllFiles'
+  value true
+end
+```
+
+where
+
+`path` is the absolute path to the `com.apple.finder.plist` plist file
+
+`entry` is the representing the plist entry `'AppleShowAllFiles'`
+
+`value` is the entry's value to boolean type: `true`