README and documentation improvement

.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": "farva@spurbury.gov",
+  "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`