Release macOS cookbook 1.2.0 (#36)

README.md

@@ -121,3 +121,4 @@ Resources
 - [ARD (Apple Remote Desktop)](./documentation/resource_ard.md)
 - [Plist](./documentation/resource_plist.md)
 - [Xcode](./documentation/resource_xcode.md)
+- [Spotlight (mdutil)](./documentation/resource_spotlight.md)

documentation/resource_spotlight.md

@@ -0,0 +1,87 @@
+spotlight
+===
+
+Use the **spotlight** resource to manage the metadata indexing state for disk volumes. This
+will primarily affect the ability to search volume contents with the macOS Spotlight feature.
+Under the hood, a **spotlight** resource executes the `mdutil` command in the `metadata_util`
+library.
+
+[Learn more about Spotlight](https://support.apple.com/en-us/HT204014).
+
+[Learn more about the `mdutil` command](https://developer.apple.com/legacy/library/documentation/Darwin/Reference/ManPages/man1/mdutil.1.html).
+
+Syntax
+------
+
+The most basic usage of a **spotlight** resource block declares a disk volume as the name property
+to **enable** metadata indexing:
+
+```ruby
+spotlight '/'
+```
+
+The full syntax for all of the properties available to the **spotlight** resource is:
+
+```ruby
+spotlight 'volume name' do
+  volume                      String # defaults to 'volume name' if not specified
+  indexed                     TrueClass, FalseClass # defaults to TrueClass if not specified
+  searchable                TrueClass, FalseClass # defaults to TrueClass if not specified
+end
+```
+
+Actions
+-------
+
+This resource has the following actions:
+
+`:set`
+
+      Set the metadata indexing state declared by the `indexed`
+property. This is the only, and default, action.
+
+
+Properties
+----------
+
+`volume`
+
+      **Ruby Type:** `String`
+
+      The name of the disk volume to manage.
+
+`indexed`
+
+      **Ruby type:** `TrueClass, FalseClass`
+
+      Whether or not the desired state of the named disk volume is to
+be indexed.
+
+`searchable`
+
+      **Ruby type:** `TrueClass, FalseClass`
+
+      Disables Spotlight searching if the index has already been
+created for the volume. Only applicable if the `indexed` property is set to `false`.
+
+Examples
+----------
+
+```ruby
+spotlight '/' # enables indexing on the boot volume
+
+spotlight 'test_disk1' do # disables indexing on 'test_disk1'
+  indexed false
+end
+
+spotlight 'enable indexing on TDD2' do
+  volume 'TDD2'
+  indexed true
+end
+
+spotlight 'disable indexing and prevent searching index on TDD-ROM' do
+  volume 'TDD-ROM'
+  indexed false
+  searchable false
+end
+```

libraries/metadata_util.rb

@@ -0,0 +1,23 @@
+include Chef::Mixin::ShellOut
+
+module MacOS
+  class MetadataUtil
+    attr_reader :status_flags
+
+    def initialize(volume)
+      mdutil_possible_states = { 'Indexing enabled.' => ['on', ''],
+                                 'Indexing disabled.' => ['off', ''],
+                                 'Indexing and searching disabled.' => ['off', '-d'] }
+
+      @status_flags = mdutil_possible_states[volume_current_state(volume)]
+                      .insert(1, volume)
+    end
+
+    def volume_current_state(volume)
+      shell_out('/usr/bin/mdutil', '-s', volume).stdout.split(':')[1].strip
+    end
+  end
+end
+
+Chef::Recipe.include(MacOS)
+Chef::Resource.include(MacOS)

metadata.rb

@@ -5,7 +5,7 @@ license 'MIT'
 description 'Resources for configuring and provisioning macOS'
 long_description 'Resources for configuring and provisioning macOS'
 chef_version '~> 13.0' if respond_to?(:chef_version)
-version '1.1.1'
+version '1.2.0'
 
 source_url 'https://github.com/Microsoft/macos-cookbook'
 issues_url 'https://github.com/Microsoft/macos-cookbook/issues'

resources/spotlight.rb

@@ -0,0 +1,39 @@
+resource_name :spotlight
+default_action :set
+
+property :volume, String, name_property: true
+property :indexed, [true, false], default: true
+property :searchable, [true, false], default: true
+
+action_class do
+  def state
+    new_resource.indexed ? 'on' : 'off'
+  end
+
+  def search
+    new_resource.searchable ? '' : '-d'
+  end
+
+  def volume_path(volume)
+    volume == '/' ? volume : ::File.join('/Volumes', volume)
+  end
+
+  def target_volume
+    volume_path(new_resource.volume)
+  end
+
+  def mdutil
+    ['/usr/bin/mdutil']
+  end
+
+  def desired_spotlight_state
+    [state, target_volume, search]
+  end
+end
+
+action :set do
+  execute "turn Spotlight indexing #{state} for #{target_volume}" do
+    command mdutil + desired_spotlight_state.insert(0, '-i')
+    not_if { MetadataUtil.new(target_volume).status_flags == desired_spotlight_state }
+  end
+end

spec/spec_helper.rb

@@ -5,6 +5,7 @@ require_relative '../libraries/macos_user'
 require_relative '../libraries/plist'
 require_relative '../libraries/xcode'
 require_relative '../libraries/xcversion'
+require_relative '../libraries/metadata_util'
 
 RSpec.configure do |config|
   config.platform = 'mac_os_x'

spec/unit/libraries/metadata_util_spec.rb

@@ -0,0 +1,59 @@
+require 'spec_helper'
+include MacOS
+
+describe MacOS::MetadataUtil do
+  context 'when passed a root volume that has indexing enabled' do
+    before do
+      allow_any_instance_of(MacOS::MetadataUtil).to receive(:volume_current_state)
+        .and_return('Indexing enabled.')
+    end
+    it 'returns an array containing the mdutil flags matching that state' do
+      md = MacOS::MetadataUtil.new('/')
+      expect(md.status_flags).to eq ['on', '/', '']
+    end
+  end
+
+  context 'when passed a test volume that has indexing disabled' do
+    before do
+      allow_any_instance_of(MacOS::MetadataUtil).to receive(:volume_current_state)
+        .and_return('Indexing disabled.')
+    end
+    it 'returns an array containing the mdutil flags matching that state' do
+      md = MacOS::MetadataUtil.new('/Volumes/test_disk1')
+      expect(md.status_flags).to eq ['off', '/Volumes/test_disk1', '']
+    end
+  end
+
+  context 'when passed a test volume that has indexing enabled' do
+    before do
+      allow_any_instance_of(MacOS::MetadataUtil).to receive(:volume_current_state)
+        .and_return('Indexing enabled.')
+    end
+    it 'returns an array containing the mdutil flags matching that state' do
+      md = MacOS::MetadataUtil.new('/Volumes/TDD2')
+      expect(md.status_flags).to eq ['on', '/Volumes/TDD2', '']
+    end
+  end
+
+  context 'when passed a test volume that has escape characters and indexing disabled' do
+    before do
+      allow_any_instance_of(MacOS::MetadataUtil).to receive(:volume_current_state)
+        .and_return('Indexing disabled.')
+    end
+    it 'returns an array containing the mdutil flags matching that state' do
+      md = MacOS::MetadataUtil.new('/Volumes/Macintosh\ TD')
+      expect(md.status_flags).to eq ['off', '/Volumes/Macintosh\ TD', '']
+    end
+  end
+
+  context 'when passed a test volume that has indexing and searching disabled' do
+    before do
+      allow_any_instance_of(MacOS::MetadataUtil).to receive(:volume_current_state)
+        .and_return('Indexing and searching disabled.')
+    end
+    it 'returns an array containing the mdutil flags matching that state' do
+      md = MacOS::MetadataUtil.new('/Volumes/TDD-ROM')
+      expect(md.status_flags).to eq ['off', '/Volumes/TDD-ROM', '-d']
+    end
+  end
+end

test/cookbooks/macos_test/.kitchen.yml

@@ -12,9 +12,8 @@ verifier:
   sudo: true
 
 platforms:
-  - name: apex/macos-10.11.6
   - name: apex/macos-10.12.6
-  - name: apex/macos-10.13.2
+  - name: apex/macos-10.13.3
 
 suites:
   - name: default
@@ -34,3 +33,10 @@ suites:
     verifier:
       inspec_tests:
         - test/smoke/xcode
+
+  - name: spotlight
+    run_list:
+      - recipe[macos_test::spotlight]
+    verifier:
+      inspec_tests:
+        - test/smoke/spotlight

test/cookbooks/macos_test/recipes/spotlight.rb

@@ -0,0 +1,44 @@
+if node['platform_version'].match?(/10.13/)
+  execute 'create test disk collection on APFS' do
+    command ['diskutil', 'apfs', 'resizeContainer',
+             'disk0s2', '25g',
+             'jhfs+', 'test_disk1', '1G',
+             'jhfs+', 'TDD2', '1G',
+             'jhfs+', 'Macintosh TD', '1G',
+             'jhfs+', 'TDD-ROM', '700MB']
+    not_if ['ls', '/Volumes/test_disk1']
+  end
+
+else
+  execute 'create test disk collection on HFS' do
+    command ['diskutil', 'resizeVolume',
+             'disk0s2', '25g',
+             'jhfs+', 'test_disk1', '1G',
+             'jhfs+', 'TDD2', '1G',
+             'jhfs+', 'Macintosh TD', '1G',
+             'jhfs+', 'TDD-ROM', '700MB']
+    not_if ['ls', '/Volumes/test_disk1']
+  end
+end
+
+spotlight '/'
+
+spotlight 'test_disk1' do
+  indexed false
+end
+
+spotlight 'enable indexing on TDD2' do
+  volume 'TDD2'
+  indexed true
+end
+
+spotlight 'disable indexing on Macintosh TD' do
+  volume 'Macintosh TD'
+  indexed false
+end
+
+spotlight 'disable indexing and prevent searching index on TDD-ROM' do
+  volume 'TDD-ROM'
+  indexed false
+  searchable false
+end

test/cookbooks/macos_test/test/smoke/spotlight/spotlight_test.rb

@@ -0,0 +1,23 @@
+control 'spotlight metadata stores for mounted volumes' do
+  desc 'they are set as intended by the smoke recipe'
+
+  describe command('/usr/bin/mdutil -s /') do
+    its('stdout') { should match "/:\n\tIndexing enabled." }
+  end
+
+  describe command('/usr/bin/mdutil -s /Volumes/test_disk1') do
+    its('stdout') { should match "/Volumes/test_disk1:\n\tIndexing disabled." }
+  end
+
+  describe command('/usr/bin/mdutil -s /Volumes/TDD2') do
+    its('stdout') { should match "/Volumes/TDD2:\n\tIndexing enabled." }
+  end
+
+  describe command('/usr/bin/mdutil -s /Volumes/Macintosh\ TD') do
+    its('stdout') { should match "/Volumes/Macintosh TD:\n\tIndexing disabled." }
+  end
+
+  describe command('/usr/bin/mdutil -s /Volumes/TDD-ROM') do
+    its('stdout') { should match "/Volumes/TDD-ROM:\n\tIndexing and searching disabled." }
+  end
+end