dockedit 1.0.0

data/dockedit

@@ -0,0 +1,1461 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# dockedit - A script to edit the macOS Dock
+# Usage: dockedit <subcommand> [options] [args]
+
+require 'rexml/document'
+require 'fileutils'
+require 'optparse'
+require 'uri'
+require 'stringio'
+
+# frozen_string_literal: true
+
+module DockEdit
+  # Current dockedit gem version.
+  VERSION = '1.0.0'
+end
+
+
+# frozen_string_literal: true
+
+module DockEdit
+  # Constants used across the dockedit implementation.
+  module Constants
+    # Absolute path to the Dock preferences plist.
+    #
+    # In tests this constant is overridden to point at a temporary copy.
+    DOCK_PLIST = File.expand_path('~/Library/Preferences/com.apple.dock.plist')
+
+    # Mapping of short folder names to full filesystem paths.
+    #
+    # Keys are regular expressions matched against user input; values are
+    # expanded paths.
+    PATH_SHORTCUTS = {
+      /^desktop$/i => File.expand_path('~/Desktop'),
+      /^downloads$/i => File.expand_path('~/Downloads'),
+      /^(home|~)$/i => File.expand_path('~'),
+      /^library$/i => File.expand_path('~/Library'),
+      /^documents$/i => File.expand_path('~/Documents'),
+      /^(applications|apps)$/i => '/Applications',
+      /^sites$/i => File.expand_path('~/Sites')
+    }.freeze
+
+    # Mapping of show-as string aliases to integer values used in the plist.
+    #
+    # 1 = fan, 2 = grid, 3 = list, 4 = auto.
+    SHOW_AS_VALUES = {
+      'f' => 1, 'fan' => 1,
+      'g' => 2, 'grid' => 2,
+      'l' => 3, 'list' => 3,
+      'a' => 4, 'auto' => 4
+    }.freeze
+
+    # Mapping of display-as string aliases to integer values used in the plist.
+    #
+    # 0 = stack, 1 = folder.
+    DISPLAY_AS_VALUES = {
+      's' => 0, 'stack' => 0,
+      'f' => 1, 'folder' => 1
+    }.freeze
+  end
+end
+
+
+# frozen_string_literal: true
+
+module DockEdit
+  # Handles fuzzy matching for application names and Dock items.
+  #
+  # Matching is based on a simple scoring system that prefers exact matches,
+  # then "starts with", then substring and abbreviation matches.
+  class Matcher
+    # Calculate a fuzzy match score between two strings.
+    #
+    # A lower score means a better match. +nil+ indicates no match at all.
+    #
+    # @param query [String] User-entered search text.
+    # @param target [String] Candidate string to score against.
+    # @return [Integer, nil] Score where 0 is best, or +nil+ when there is no match.
+    def self.match_score(query, target)
+      return nil if target.nil? || target.empty?
+
+      query = query.downcase
+      target = target.downcase
+
+      # Exact match - best score
+      return 0 if target == query
+
+      # Starts with query
+      return 1 if target.start_with?(query)
+
+      # Contains match - score based on position
+      if target.include?(query)
+        return 2 + target.index(query)
+      end
+
+      # Abbreviation match (e.g., "vscode" matches "Visual Studio Code")
+      query_chars = query.chars
+      target_pos = 0
+      matched = true
+
+      query_chars.each do |char|
+        found = false
+        while target_pos < target.length
+          if target[target_pos] == char
+            found = true
+            target_pos += 1
+            break
+          end
+          target_pos += 1
+        end
+        unless found
+          matched = false
+          break
+        end
+      end
+
+      return 100 + target.length if matched
+
+      nil
+    end
+
+    # Check whether +target+ fuzzily matches +query+.
+    #
+    # @param query [String]
+    # @param target [String]
+    # @return [Boolean] +true+ if {#match_score} returns a non-nil score.
+    def self.fuzzy_match?(query, target)
+      !match_score(query, target).nil?
+    end
+
+    # Find the best-matching item index in a Dock array.
+    #
+    # This scans a list of Dock tile `<dict>` elements and finds the index
+    # whose label, bundle identifier, or (optionally) URL path best matches
+    # +query+.
+    #
+    # @param items_array [Array<REXML::Element>] Array of tile `<dict>` elements.
+    # @param query [String] Search term (app name, bundle id, or path fragment).
+    # @param check_url [Boolean] Whether to also consider the folder URL path.
+    # @return [Array<(Integer, String)>] A pair of `[index, display_name]`, where
+    #   +index+ is the best entry index or +nil+ when nothing matches.
+    def self.find_item_index(items_array, query, check_url: false)
+      best_score = nil
+      best_name = nil
+      best_index = nil
+
+      items_array.each_with_index do |item_dict, index|
+        next unless item_dict.is_a?(REXML::Element) && item_dict.name == 'dict'
+
+        tile_data = PlistReader.get_tile_data(item_dict)
+        next unless tile_data
+
+        file_label = PlistReader.get_tile_value(tile_data, 'file-label')
+        bundle_id = PlistReader.get_tile_value(tile_data, 'bundle-identifier')
+
+        scores = []
+        scores << match_score(query, file_label)
+        scores << match_score(query, bundle_id)
+
+        # For folders, also check URL path
+        if check_url
+          url_string = PlistReader.get_file_data_url(tile_data)
+          if url_string
+            # Extract path from file:// URL and decode
+            path = URI.decode_www_form_component(url_string.sub(%r{^file://}, '').chomp('/'))
+            basename = File.basename(path)
+            scores << match_score(query, path)
+            scores << match_score(query, basename)
+          end
+        end
+
+        current_score = scores.compact.min
+        next unless current_score
+
+        name = file_label || bundle_id || 'Unknown'
+        name_length = name.length
+
+        if best_score.nil? || current_score < best_score ||
+           (current_score == best_score && name_length < (best_name&.length || 999))
+          best_score = current_score
+          best_name = name
+          best_index = index
+        end
+      end
+
+      [best_index, best_name]
+    end
+
+    # Backwards-compatible alias for finding app indices.
+    #
+    # @param apps_array [Array<REXML::Element>] App tile `<dict>` elements.
+    # @param query [String] Search term.
+    # @return [Array<(Integer, String)>] See {#find_item_index}.
+    def self.find_app_index(apps_array, query)
+      find_item_index(apps_array, query, check_url: false)
+    end
+  end
+end
+
+
+# frozen_string_literal: true
+
+module DockEdit
+  # Utility functions for handling user-supplied filesystem paths.
+  module PathUtils
+    include Constants
+
+    # Expand a path shortcut or user path into a full filesystem path.
+    #
+    # Recognizes shortcuts such as "desktop", "downloads", "home", "~",
+    # "applications", etc., falling back to +File.expand_path+.
+    #
+    # @param path [String] Raw path or shortcut.
+    # @return [String] Expanded absolute path with trailing slash removed.
+    def self.expand_path_shortcut(path)
+      PATH_SHORTCUTS.each do |pattern, expanded|
+        return expanded if path.match?(pattern)
+      end
+      # Not a shortcut, expand ~ and return
+      File.expand_path(path).chomp('/')
+    end
+
+    # Determine whether the given path refers to a folder (not an app bundle).
+    #
+    # This respects path shortcuts and returns +true+ only for existing
+    # directories that do not end in ".app".
+    #
+    # @param path [String] Raw path or shortcut.
+    # @return [Boolean]
+    def self.folder_path?(path)
+      expanded = expand_path_shortcut(path)
+      File.directory?(expanded) && !expanded.end_with?('.app')
+    end
+
+    # Check whether the given string looks like an explicit app bundle path.
+    #
+    # @param path [String]
+    # @return [Boolean] +true+ if the string ends with ".app" and contains a '/'.
+    def self.explicit_app_path?(path)
+      path.end_with?('.app') && path.include?('/')
+    end
+  end
+end
+
+
+# frozen_string_literal: true
+
+module DockEdit
+  # Handles reading and parsing Dock and app plist data.
+  class PlistReader
+    include Constants
+
+    # Extract the +tile-data+ `<dict>` from a Dock tile `<dict>`.
+    #
+    # @param app_dict [REXML::Element] Tile `<dict>` element.
+    # @return [REXML::Element, nil] The nested +tile-data+ dict, or +nil+.
+    def self.get_tile_data(app_dict)
+      current_key = nil
+      app_dict.elements.each do |elem|
+        if elem.name == 'key'
+          current_key = elem.text
+        elsif elem.name == 'dict' && current_key == 'tile-data'
+          return elem
+        end
+      end
+      nil
+    end
+
+    # Look up a string value in a tile-data `<dict>`.
+    #
+    # @param tile_data [REXML::Element] Tile-data `<dict>`.
+    # @param key_name [String] Name of the key to retrieve.
+    # @return [String, nil] The associated string value, or +nil+.
+    def self.get_tile_value(tile_data, key_name)
+      current_key = nil
+      tile_data.elements.each do |elem|
+        if elem.name == 'key'
+          current_key = elem.text
+        elsif current_key == key_name
+          return elem.text if elem.name == 'string'
+          return nil
+        end
+      end
+      nil
+    end
+
+    # Extract the `_CFURLString` from the nested +file-data+ dict.
+    #
+    # @param tile_data [REXML::Element] Tile-data `<dict>`.
+    # @return [String, nil] The URL string, or +nil+ if none is present.
+    def self.get_file_data_url(tile_data)
+      current_key = nil
+      tile_data.elements.each do |elem|
+        if elem.name == 'key'
+          current_key = elem.text
+        elsif elem.name == 'dict' && current_key == 'file-data'
+          return get_tile_value(elem, '_CFURLString')
+        end
+      end
+      nil
+    end
+
+    # Get the `persistent-apps` array from a Dock plist document.
+    #
+    # @param doc [REXML::Document]
+    # @return [REXML::Element, nil] The `<array>` element, or +nil+.
+    def self.get_persistent_apps(doc)
+      get_plist_array(doc, 'persistent-apps')
+    end
+
+    # Get the `persistent-others` array from a Dock plist document.
+    #
+    # @param doc [REXML::Document]
+    # @return [REXML::Element, nil] The `<array>` element, or +nil+.
+    def self.get_persistent_others(doc)
+      get_plist_array(doc, 'persistent-others')
+    end
+
+    # Get a named array from the Dock plist root `<dict>`.
+    #
+    # @param doc [REXML::Document]
+    # @param array_name [String] Name of the array key.
+    # @return [REXML::Element, nil] The `<array>` element, or +nil+.
+    def self.get_plist_array(doc, array_name)
+      root_dict = doc.root.elements['dict']
+      return nil unless root_dict
+
+      current_key = nil
+      root_dict.elements.each do |elem|
+        if elem.name == 'key'
+          current_key = elem.text
+        elsif elem.name == 'array' && current_key == array_name
+          return elem
+        end
+      end
+
+      nil
+    end
+
+    # Load and parse the Dock plist as XML.
+    #
+    # The file at {DockEdit::Constants::DOCK_PLIST} is converted to XML form
+    # using +plutil+ before being read.
+    #
+    # @return [REXML::Document] Parsed Dock plist document.
+    def self.load_dock_plist
+      unless system("plutil -convert xml1 '#{DOCK_PLIST}' 2>/dev/null")
+        $stderr.puts "Error: Failed to convert Dock plist to XML"
+        exit 1
+      end
+
+      plist_content = File.read(DOCK_PLIST)
+      REXML::Document.new(plist_content)
+    end
+
+    # Read and parse +Info.plist+ from an app bundle.
+    #
+    # The plist is copied to a temporary file and converted to XML before
+    # parsing. Selected keys are extracted into a flat Ruby hash.
+    #
+    # @param app_path [String] Absolute path to an `.app` bundle.
+    # @return [Hash, nil] Hash of plist keys to values, or +nil+ if the
+    #   plist cannot be read.
+    def self.read_app_info(app_path)
+      info_plist = File.join(app_path, 'Contents', 'Info.plist')
+      return nil unless File.exist?(info_plist)
+
+      # Convert to XML and read
+      temp_plist = "/tmp/dockedit_info_#{$$}.plist"
+      FileUtils.cp(info_plist, temp_plist)
+      system("plutil -convert xml1 '#{temp_plist}' 2>/dev/null")
+
+      content = File.read(temp_plist)
+      File.delete(temp_plist) if File.exist?(temp_plist)
+
+      doc = REXML::Document.new(content)
+      root_dict = doc.root.elements['dict']
+      return nil unless root_dict
+
+      info = {}
+      current_key = nil
+
+      root_dict.elements.each do |elem|
+        if elem.name == 'key'
+          current_key = elem.text
+        elsif current_key
+          case elem.name
+          when 'string'
+            info[current_key] = elem.text
+          when 'array'
+            # For arrays, get first string element
+            first_string = elem.elements['string']
+            info[current_key] = first_string.text if first_string
+          end
+          current_key = nil
+        end
+      end
+
+      info
+    end
+  end
+end
+
+
+# frozen_string_literal: true
+
+module DockEdit
+  # Handles writing Dock plist data and restarting the Dock process.
+  class PlistWriter
+    include Constants
+
+    # Write the modified Dock plist and restart the Dock.
+    #
+    # The provided document is pretty-printed, written to
+    # {DockEdit::Constants::DOCK_PLIST}, converted back to binary format,
+    # and the Dock process is restarted. Success messages are printed and
+    # the process exits with status 0. On error, a message is printed and
+    # the process exits with status 1.
+    #
+    # @param doc [REXML::Document] Modified Dock plist document.
+    # @param success_messages [String, Array<String>] Message or messages to
+    #   print after a successful write.
+    # @return [void]
+    def self.write_plist_and_restart(doc, success_messages)
+      formatter = REXML::Formatters::Pretty.new(2)
+      formatter.compact = true
+
+      output = StringIO.new
+      output << %{<?xml version="1.0" encoding="UTF-8"?>\n}
+      output << %{<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n}
+      formatter.write(doc.root, output)
+      output << "\n"
+
+      begin
+        File.write(DOCK_PLIST, output.string)
+      rescue => e
+        $stderr.puts "Error: Failure to update Dock plist - #{e.message}"
+        exit 1
+      end
+
+      # Convert back to binary and restart Dock
+      unless system("plutil -convert binary1 '#{DOCK_PLIST}' 2>/dev/null")
+        $stderr.puts "Error: Failure to update Dock plist"
+        exit 1
+      end
+
+      system('killall Dock')
+
+      # Handle single message or array of messages
+      messages = success_messages.is_a?(Array) ? success_messages : [success_messages]
+      messages.each { |msg| puts msg }
+      exit 0
+    end
+  end
+end
+
+
+# frozen_string_literal: true
+
+module DockEdit
+  # Handles finding applications on disk using Spotlight (mdfind).
+  #
+  # This class is used by commands that accept an application name (e.g. "Safari")
+  # and need to resolve it to a full `.app` bundle path.
+  class AppFinder
+    # Find an application bundle on disk using Spotlight.
+    #
+    # The search is limited to `/Applications` and `/System/Applications`.
+    # Results are scored using {DockEdit::Matcher.match_score} and the best
+    # matching `.app` path is returned.
+    #
+    # @param query [String] Human-friendly app name to search for.
+    # @return [String, nil] Absolute path to the best matching `.app`, or +nil+
+    #   if no match is found.
+    def self.find_app_on_disk(query)
+      # Search in /Applications and /System/Applications
+      result = `mdfind -onlyin /Applications -onlyin /System/Applications 'kMDItemKind == "Application" && kMDItemDisplayName == "*#{query}*"cd' 2>/dev/null`.strip
+
+      if result.empty?
+        # Fallback to filename search
+        result = `mdfind -onlyin /Applications -onlyin /System/Applications 'kMDItemFSName == "*#{query}*.app"cd' 2>/dev/null`.strip
+      end
+
+      return nil if result.empty?
+
+      apps = result.split("\n").select { |p| p.end_with?('.app') }
+      return nil if apps.empty?
+
+      # Score and sort by best match (shortest name wins on equal score)
+      scored = apps.map do |path|
+        name = File.basename(path, '.app')
+        score = Matcher.match_score(query, name)
+        [path, name, score || 999, name.length]
+      end
+
+      # Sort by score, then by name length
+      scored.sort_by! { |_, _, score, len| [score, len] }
+
+      scored.first&.first
+    end
+  end
+end
+
+
+# frozen_string_literal: true
+
+module DockEdit
+  # Factory for creating Dock tile elements.
+  #
+  # These helpers construct the REXML structures that represent apps,
+  # folders, and spacer tiles inside the Dock plist.
+  class TileFactory
+    # Create a spacer tile element.
+    #
+    # @param small [Boolean] When +true+, create a half-size spacer.
+    # @return [REXML::Element] Newly created tile `<dict>` element.
+    def self.create_spacer_tile(small: false)
+      tile_type = small ? 'small-spacer-tile' : 'spacer-tile'
+
+      spacer = REXML::Element.new('dict')
+
+      key1 = REXML::Element.new('key')
+      key1.text = 'tile-data'
+      spacer.add(key1)
+
+      tile_data = REXML::Element.new('dict')
+      label_key = REXML::Element.new('key')
+      label_key.text = 'file-label'
+      tile_data.add(label_key)
+      label_string = REXML::Element.new('string')
+      label_string.text = ''
+      tile_data.add(label_string)
+      spacer.add(tile_data)
+
+      key2 = REXML::Element.new('key')
+      key2.text = 'tile-type'
+      spacer.add(key2)
+
+      type_string = REXML::Element.new('string')
+      type_string.text = tile_type
+      spacer.add(type_string)
+
+      spacer
+    end
+
+    # Create an app tile element.
+    #
+    # @param app_path [String] Absolute path to the `.app` bundle.
+    # @param app_info [Hash] Parsed plist info from {PlistReader.read_app_info}.
+    # @return [REXML::Element] Newly created tile `<dict>` element.
+    def self.create_app_tile(app_path, app_info)
+      app_dict = REXML::Element.new('dict')
+
+      # tile-data key
+      td_key = REXML::Element.new('key')
+      td_key.text = 'tile-data'
+      app_dict.add(td_key)
+
+      # tile-data dict
+      tile_data = REXML::Element.new('dict')
+
+      # bundle-identifier
+      add_plist_key_value(tile_data, 'bundle-identifier', 'string', app_info['CFBundleIdentifier'])
+
+      # dock-extra
+      add_plist_key_value(tile_data, 'dock-extra', 'false', nil)
+
+      # file-data dict
+      fd_key = REXML::Element.new('key')
+      fd_key.text = 'file-data'
+      tile_data.add(fd_key)
+
+      file_data = REXML::Element.new('dict')
+      add_plist_key_value(file_data, '_CFURLString', 'string', "file://#{URI.encode_www_form_component(app_path).gsub('%2F', '/')}/")
+      add_plist_key_value(file_data, '_CFURLStringType', 'integer', '15')
+      tile_data.add(file_data)
+
+      # file-label
+      label = app_info['CFBundleName'] || app_info['CFBundleDisplayName'] || File.basename(app_path, '.app')
+      add_plist_key_value(tile_data, 'file-label', 'string', label)
+
+      # file-mod-date
+      add_plist_key_value(tile_data, 'file-mod-date', 'integer', '0')
+
+      # file-type
+      add_plist_key_value(tile_data, 'file-type', 'integer', '41')
+
+      # is-beta
+      add_plist_key_value(tile_data, 'is-beta', 'false', nil)
+
+      # parent-mod-date
+      add_plist_key_value(tile_data, 'parent-mod-date', 'integer', '0')
+
+      app_dict.add(tile_data)
+
+      # tile-type key
+      tt_key = REXML::Element.new('key')
+      tt_key.text = 'tile-type'
+      app_dict.add(tt_key)
+
+      tt_value = REXML::Element.new('string')
+      tt_value.text = 'file-tile'
+      app_dict.add(tt_value)
+
+      app_dict
+    end
+
+    # Create a folder tile element.
+    #
+    # @param folder_path [String] Absolute path to the folder.
+    # @param show_as [Integer] Show-as value (1=fan, 2=grid, 3=list, 4=auto).
+    # @param display_as [Integer] Display-as value (0=stack, 1=folder).
+    # @return [REXML::Element] Newly created folder tile `<dict>` element.
+    def self.create_folder_tile(folder_path, show_as: 4, display_as: 1)
+      folder_dict = REXML::Element.new('dict')
+
+      # tile-data key
+      td_key = REXML::Element.new('key')
+      td_key.text = 'tile-data'
+      folder_dict.add(td_key)
+
+      # tile-data dict
+      tile_data = REXML::Element.new('dict')
+
+      # arrangement (0 = by name)
+      add_plist_key_value(tile_data, 'arrangement', 'integer', '0')
+
+      # displayas (0 = stack, 1 = folder)
+      add_plist_key_value(tile_data, 'displayas', 'integer', display_as.to_s)
+
+      # file-data dict
+      fd_key = REXML::Element.new('key')
+      fd_key.text = 'file-data'
+      tile_data.add(fd_key)
+
+      file_data = REXML::Element.new('dict')
+      encoded_path = URI.encode_www_form_component(folder_path).gsub('%2F', '/')
+      add_plist_key_value(file_data, '_CFURLString', 'string', "file://#{encoded_path}/")
+      add_plist_key_value(file_data, '_CFURLStringType', 'integer', '15')
+      tile_data.add(file_data)
+
+      # file-label
+      label = File.basename(folder_path)
+      add_plist_key_value(tile_data, 'file-label', 'string', label)
+
+      # file-mod-date
+      add_plist_key_value(tile_data, 'file-mod-date', 'integer', '0')
+
+      # file-type
+      add_plist_key_value(tile_data, 'file-type', 'integer', '2')
+
+      # parent-mod-date
+      add_plist_key_value(tile_data, 'parent-mod-date', 'integer', '0')
+
+      # preferreditemsize (-1 = default)
+      add_plist_key_value(tile_data, 'preferreditemsize', 'integer', '-1')
+
+      # showas (1=fan, 2=grid, 3=list, 4=auto)
+      add_plist_key_value(tile_data, 'showas', 'integer', show_as.to_s)
+
+      folder_dict.add(tile_data)
+
+      # tile-type key
+      tt_key = REXML::Element.new('key')
+      tt_key.text = 'tile-type'
+      folder_dict.add(tt_key)
+
+      tt_value = REXML::Element.new('string')
+      tt_value.text = 'directory-tile'
+      folder_dict.add(tt_value)
+
+      folder_dict
+    end
+
+    # Helper to add a key/value pair to a plist `<dict>` element.
+    #
+    # @param dict [REXML::Element] Target `<dict>` element.
+    # @param key_name [String] Key to add.
+    # @param value_type [String] Name of the value element type (e.g. "string").
+    # @param value [String, nil] Optional text value for the element.
+    # @return [void]
+    def self.add_plist_key_value(dict, key_name, value_type, value)
+      key = REXML::Element.new('key')
+      key.text = key_name
+      dict.add(key)
+
+      val_elem = REXML::Element.new(value_type)
+      val_elem.text = value if value
+      dict.add(val_elem)
+    end
+  end
+end
+
+
+# frozen_string_literal: true
+
+module DockEdit
+  # Handles updating folder tile properties in the Dock plist.
+  #
+  # These helpers mutate existing folder tiles to change view and style
+  # without recreating them.
+  class FolderUpdater
+    # Update the +showas+ value for an existing folder tile.
+    #
+    # @param folder_dict [REXML::Element] Folder tile `<dict>` element.
+    # @param show_as [Integer] New show-as value (1=fan, 2=grid, 3=list, 4=auto).
+    # @return [Boolean] +true+ if the value was updated or added.
+    def self.update_folder_showas(folder_dict, show_as)
+      update_folder_integer_key(folder_dict, 'showas', show_as)
+    end
+
+    # Update the +displayas+ value for an existing folder tile.
+    #
+    # @param folder_dict [REXML::Element] Folder tile `<dict>` element.
+    # @param display_as [Integer] New display-as value (0=stack, 1=folder).
+    # @return [Boolean] +true+ if the value was updated or added.
+    def self.update_folder_displayas(folder_dict, display_as)
+      update_folder_integer_key(folder_dict, 'displayas', display_as)
+    end
+
+    # Update an integer key inside folder tile-data.
+    #
+    # If the key already exists its integer value is replaced; otherwise a new
+    # key/value pair is appended.
+    #
+    # @param folder_dict [REXML::Element] Folder tile `<dict>` element.
+    # @param key_name [String] Name of the integer key inside +tile-data+.
+    # @param value [Integer] New integer value to set.
+    # @return [Boolean] +true+ if the value was updated or added, +false+ if
+    #   no +tile-data+ section could be found.
+    def self.update_folder_integer_key(folder_dict, key_name, value)
+      tile_data = PlistReader.get_tile_data(folder_dict)
+      return false unless tile_data
+
+      # Find and update the key
+      current_key = nil
+      tile_data.elements.each do |elem|
+        if elem.name == 'key' && elem.text == key_name
+          current_key = elem
+        elsif current_key && elem.name == 'integer'
+          elem.text = value.to_s
+          return true
+        end
+      end
+
+      # If key doesn't exist, add it
+      TileFactory.add_plist_key_value(tile_data, key_name, 'integer', value.to_s)
+      true
+    end
+  end
+end
+
+
+# frozen_string_literal: true
+
+module DockEdit
+  # Utility functions for parsing and formatting Dock-related values.
+  module Parsers
+    include Constants
+
+    # Parse a show-as argument into an integer value.
+    #
+    # Accepts symbolic forms like "fan", "grid", "list", "auto" (and their
+    # single-letter aliases) and returns the corresponding integer constant.
+    #
+    # @param value [String, nil] Raw user input.
+    # @return [Integer, nil] Parsed show-as value, or +nil+ if +value+ is +nil+.
+    def self.parse_show_as(value)
+      return nil if value.nil?
+
+      key = value.downcase
+      SHOW_AS_VALUES[key] || 4
+    end
+
+    # Convert a numeric show-as value into a human-readable name.
+    #
+    # @param value [Integer] Numeric show-as value.
+    # @return [String] One of "fan", "grid", "list", or "auto".
+    def self.show_as_name(value)
+      case value
+      when 1 then 'fan'
+      when 2 then 'grid'
+      when 3 then 'list'
+      when 4 then 'auto'
+      else 'auto'
+      end
+    end
+
+    # Parse a display-as argument into an integer value.
+    #
+    # Accepts "stack"/"s" and "folder"/"f".
+    #
+    # @param value [String, nil] Raw user input.
+    # @return [Integer, nil] Parsed display-as value, or +nil+ if invalid or +nil+.
+    def self.parse_display_as(value)
+      return nil if value.nil?
+
+      key = value.downcase
+      DISPLAY_AS_VALUES[key]
+    end
+
+    # Convert a numeric display-as value into a human-readable name.
+    #
+    # @param value [Integer] Numeric display-as value.
+    # @return [String] Either "stack" or "folder".
+    def self.display_as_name(value)
+      case value
+      when 0 then 'stack'
+      when 1 then 'folder'
+      else 'stack'
+      end
+    end
+  end
+end
+
+
+# frozen_string_literal: true
+
+module DockEdit
+  # Main class for managing Dock state and high-level operations.
+  #
+  # A {Dock} instance wraps a parsed Dock plist and provides helpers for
+  # locating and mutating app and folder tiles.
+  class Dock
+    attr_reader :doc, :apps_array, :others_array
+
+    # Create a new Dock wrapper around the current Dock plist.
+    #
+    # The plist is loaded via {PlistReader.load_dock_plist} and the
+    # `persistent-apps` and `persistent-others` arrays are extracted.
+    #
+    # @raise [SystemExit] Exits with status 1 if the arrays cannot be found.
+    def initialize
+      @doc = PlistReader.load_dock_plist
+      @apps_array = PlistReader.get_persistent_apps(@doc)
+      @others_array = PlistReader.get_persistent_others(@doc)
+
+      unless @apps_array && @others_array
+        $stderr.puts "Error: Could not find dock arrays in plist"
+        exit 1
+      end
+    end
+
+    # Persist changes to the Dock plist and restart the Dock.
+    #
+    # @param messages [String, Array<String>] Message or messages to print.
+    # @return [void]
+    def save(messages)
+      PlistWriter.write_plist_and_restart(@doc, messages)
+    end
+
+    # Find an application tile by name or bundle identifier.
+    #
+    # @param query [String] Search term.
+    # @return [Array<(Integer, String)>] A pair of `[index, display_name]`
+    #   from the apps array, or `[nil, nil]` if not found.
+    def find_app(query)
+      app_dicts = @apps_array.elements.to_a.select { |e| e.is_a?(REXML::Element) && e.name == 'dict' }
+      Matcher.find_app_index(app_dicts, query)
+    end
+
+    # Find a folder tile by name, bundle identifier, or path.
+    #
+    # @param query [String] Search term (name or path).
+    # @param check_url [Boolean] Whether to match against the folder URL path.
+    # @return [Array<(Integer, String)>] A pair of `[index, display_name]`
+    #   from the folders array, or `[nil, nil]` if not found.
+    def find_folder(query, check_url: false)
+      folder_dicts = @others_array.elements.to_a.select { |e| e.is_a?(REXML::Element) && e.name == 'dict' }
+      Matcher.find_item_index(folder_dicts, query, check_url: check_url)
+    end
+
+    # Find a tile in either the apps or folders section.
+    #
+    # Apps are searched first; if no match is found, folders are checked.
+    #
+    # @param query [String] Search term.
+    # @param check_url [Boolean] Whether to match against folder URL paths.
+    # @return [Array] A triple of `[array, element, display_name]`, or
+    #   `[nil, nil, nil]` if nothing matches.
+    def find_item(query, check_url: false)
+      # Try apps first
+      index, name = find_app(query)
+      if index
+        app_dicts = @apps_array.elements.to_a.select { |e| e.is_a?(REXML::Element) && e.name == 'dict' }
+        return [@apps_array, app_dicts[index], name]
+      end
+
+      # Try folders
+      index, name = find_folder(query, check_url: check_url)
+      if index
+        folder_dicts = @others_array.elements.to_a.select { |e| e.is_a?(REXML::Element) && e.name == 'dict' }
+        return [@others_array, folder_dicts[index], name]
+      end
+
+      [nil, nil, nil]
+    end
+
+    # Return all app tile `<dict>` elements.
+    #
+    # @return [Array<REXML::Element>]
+    def get_app_dicts
+      @apps_array.elements.to_a.select { |e| e.is_a?(REXML::Element) && e.name == 'dict' }
+    end
+
+    # Return all folder tile `<dict>` elements.
+    #
+    # @return [Array<REXML::Element>]
+    def get_folder_dicts
+      @others_array.elements.to_a.select { |e| e.is_a?(REXML::Element) && e.name == 'dict' }
+    end
+  end
+end
+
+
+# frozen_string_literal: true
+
+module DockEdit
+  # Command handlers for `dockedit` subcommands.
+  #
+  # Each method in this module implements the behavior for a single
+  # subcommand, operating on the Dock plist via {DockEdit::Dock}.
+  module Commands
+    # Implementation of the `space` subcommand.
+    #
+    # Inserts one or more spacer tiles in the apps section of the Dock.
+    #
+    # @param args [Array<String>] Command-line arguments for the subcommand.
+    # @return [void]
+    def self.space(args)
+      options = { small: false, after: [] }
+
+      parser = CLI.space_parser(options)
+      parser.order!(args)
+
+      small = options[:small]
+      after_apps = options[:after]
+      spacer_type = small ? 'Small space' : 'Space'
+
+      dock = Dock.new
+      messages = []
+
+      if after_apps.empty?
+        # Add single space at end
+        spacer = TileFactory.create_spacer_tile(small: small)
+        dock.apps_array.add(spacer)
+        messages << "#{spacer_type} added to end of Dock."
+      else
+        # Process each --after app
+        after_apps.each do |after_app|
+          # Re-fetch app_dicts each time since array changes after insert
+          app_dicts = dock.get_app_dicts
+
+          index, name = dock.find_app(after_app)
+          unless index
+            $stderr.puts "Error: App '#{after_app}' not found in Dock"
+            exit 1
+          end
+
+          spacer = TileFactory.create_spacer_tile(small: small)
+          dock.apps_array.insert_after(app_dicts[index], spacer)
+          messages << "#{spacer_type} inserted after '#{name}'."
+        end
+      end
+
+      dock.save(messages)
+    end
+
+    # Implementation of the `add` subcommand.
+    #
+    # Adds applications and/or folders to the Dock, optionally positioning
+    # them relative to an existing item and updating folder view/style.
+    #
+    # @param args [Array<String>] Command-line arguments for the subcommand.
+    # @return [void]
+    def self.add(args)
+      options = { after: nil, show_as: nil, display_as: nil }
+
+      parser = CLI.add_parser(options)
+      parser.permute!(args)
+
+      after_target = options[:after]
+      show_as = options[:show_as]
+      display_as = options[:display_as]
+
+      if args.empty?
+        $stderr.puts parser
+        exit 1
+      end
+
+      dock = Dock.new
+      messages = []
+      last_inserted_app_element = nil
+      last_inserted_folder_element = nil
+
+      # Find initial insertion point if --after specified
+      if after_target
+        after_array, after_element, _after_name = dock.find_item(after_target, check_url: true)
+
+        if after_element
+          if after_array == dock.apps_array
+            last_inserted_app_element = after_element
+          else
+            last_inserted_folder_element = after_element
+          end
+        else
+          $stderr.puts "Error: '#{after_target}' not found in Dock"
+          exit 1
+        end
+      end
+
+      # Process each argument
+      args.each do |item_query|
+        # Determine if this is a folder or app
+        if PathUtils.folder_path?(item_query)
+          # It's a folder
+          folder_path = PathUtils.expand_path_shortcut(item_query)
+
+          unless File.directory?(folder_path)
+            $stderr.puts "Error: Folder '#{folder_path}' not found"
+            exit 1
+          end
+
+          folder_name = File.basename(folder_path)
+
+          # Check if folder is already in dock
+          existing_index, existing_name = dock.find_folder(folder_path, check_url: true)
+
+          if existing_index
+            # If show_as or display_as was specified, update the existing folder
+            updates = []
+            folder_dicts = dock.get_folder_dicts
+            if show_as
+              FolderUpdater.update_folder_showas(folder_dicts[existing_index], show_as)
+              updates << "view=#{Parsers.show_as_name(show_as)}"
+            end
+            if display_as
+              FolderUpdater.update_folder_displayas(folder_dicts[existing_index], display_as)
+              updates << "style=#{Parsers.display_as_name(display_as)}"
+            end
+
+            if updates.any?
+              messages << "'#{existing_name}' updated (#{updates.join(', ')})."
+            else
+              $stderr.puts "Warning: '#{existing_name}' is already in the Dock, skipping"
+            end
+            next
+          end
+
+          # Create the folder tile (use defaults if not specified)
+          folder_tile = TileFactory.create_folder_tile(folder_path, show_as: show_as || 4, display_as: display_as || 1)
+
+          if last_inserted_folder_element
+            dock.others_array.insert_after(last_inserted_folder_element, folder_tile)
+          else
+            dock.others_array.add(folder_tile)
+          end
+
+          last_inserted_folder_element = folder_tile
+          messages << "'#{folder_name}' folder added to Dock."
+
+        elsif PathUtils.explicit_app_path?(item_query)
+          # Explicit app path given
+          app_path = File.expand_path(item_query)
+
+          unless File.exist?(File.join(app_path, 'Contents', 'Info.plist'))
+            $stderr.puts "Error: Application path '#{app_path}' not found"
+            exit 1
+          end
+
+          app_info = PlistReader.read_app_info(app_path)
+          unless app_info && app_info['CFBundleIdentifier']
+            $stderr.puts "Error: Could not read app info from '#{app_path}'"
+            exit 1
+          end
+
+          app_name = app_info['CFBundleName'] || app_info['CFBundleDisplayName'] || File.basename(app_path, '.app')
+
+          # Check if app is already in dock
+          existing_index, existing_name = dock.find_app(app_info['CFBundleIdentifier'])
+
+          if existing_index
+            $stderr.puts "Warning: '#{existing_name}' is already in the Dock, skipping"
+            next
+          end
+
+          # Create the app tile
+          app_tile = TileFactory.create_app_tile(app_path, app_info)
+
+          if last_inserted_app_element
+            dock.apps_array.insert_after(last_inserted_app_element, app_tile)
+            last_inserted_app_element = app_tile
+          else
+            dock.apps_array.add(app_tile)
+          end
+
+          messages << "'#{app_name}' added to Dock."
+
+        else
+          # Search for app by name
+          app_path = AppFinder.find_app_on_disk(item_query)
+          unless app_path
+            $stderr.puts "Error: App '#{item_query}' not found"
+            exit 1
+          end
+
+          app_info = PlistReader.read_app_info(app_path)
+          unless app_info && app_info['CFBundleIdentifier']
+            $stderr.puts "Error: Could not read app info from '#{app_path}'"
+            exit 1
+          end
+
+          app_name = app_info['CFBundleName'] || app_info['CFBundleDisplayName'] || File.basename(app_path, '.app')
+
+          # Check if app is already in dock
+          existing_index, existing_name = dock.find_app(app_info['CFBundleIdentifier'])
+
+          if existing_index
+            $stderr.puts "Warning: '#{existing_name}' is already in the Dock, skipping"
+            next
+          end
+
+          # Create the app tile
+          app_tile = TileFactory.create_app_tile(app_path, app_info)
+
+          if last_inserted_app_element
+            dock.apps_array.insert_after(last_inserted_app_element, app_tile)
+            last_inserted_app_element = app_tile
+          else
+            dock.apps_array.add(app_tile)
+          end
+
+          messages << "'#{app_name}' added to Dock."
+        end
+      end
+
+      if messages.empty?
+        $stderr.puts "No items were added to the Dock"
+        exit 1
+      end
+
+      dock.save(messages)
+    end
+
+    # Implementation of the `remove` subcommand.
+    #
+    # Removes apps and/or folders from the Dock by name, bundle identifier,
+    # or path.
+    #
+    # @param args [Array<String>] Command-line arguments for the subcommand.
+    # @return [void]
+    def self.remove(args)
+      parser = CLI.remove_parser({})
+      parser.order!(args)
+
+      if args.empty?
+        $stderr.puts parser
+        exit 1
+      end
+
+      dock = Dock.new
+      messages = []
+
+      # Process each argument
+      args.each do |item_query|
+        found = false
+
+        # Determine if this looks like a path
+        is_path = item_query.include?('/')
+
+        # First check persistent-apps
+        index, name = dock.find_app(item_query)
+
+        if index
+          app_dicts = dock.get_app_dicts
+          dock.apps_array.delete(app_dicts[index])
+          messages << "'#{name}' removed from Dock."
+          found = true
+        end
+
+        # If not found in apps, check persistent-others (folders)
+        unless found
+          index, name = dock.find_folder(item_query, check_url: is_path)
+
+          if index
+            folder_dicts = dock.get_folder_dicts
+            dock.others_array.delete(folder_dicts[index])
+            messages << "'#{name}' removed from Dock."
+            found = true
+          end
+        end
+
+        unless found
+          $stderr.puts "Warning: '#{item_query}' not found in Dock, skipping"
+        end
+      end
+
+      if messages.empty?
+        $stderr.puts "No items were removed from the Dock"
+        exit 1
+      end
+
+      dock.save(messages)
+    end
+
+    # Implementation of the `move` subcommand.
+    #
+    # Moves an existing Dock item after another item in the same section.
+    #
+    # @param args [Array<String>] Command-line arguments for the subcommand.
+    # @return [void]
+    def self.move(args)
+      # Accept either order: move --after TARGET ITEM or move ITEM --after TARGET
+      options = { after: nil }
+      parser = CLI.move_parser(options)
+      parser.permute!(args)
+
+      # Now, args should contain the non-option arguments (either [item] or [target, item] or [item, target])
+      after_target = options[:after]
+
+      # Accept either order: --after TARGET ITEM or ITEM --after TARGET
+      item_query = nil
+      if after_target && args.length == 1
+        item_query = args.first
+      elsif after_target && args.length == 2
+        # Try to infer which is the item and which is the target
+        if args[0].downcase == after_target.downcase
+          item_query = args[1]
+        elsif args[1].downcase == after_target.downcase
+          item_query = args[0]
+        else
+          # Default: treat first as item
+          item_query = args[0]
+        end
+      else
+        $stderr.puts parser
+        $stderr.puts "\nError: You must specify an item to move and a target with --after."
+        exit 1
+      end
+
+      if !after_target || !item_query
+        $stderr.puts parser
+        $stderr.puts "\nError: You must specify an item to move and a target with --after."
+        exit 1
+      end
+
+      dock = Dock.new
+
+      # Find the item to move (check apps first, then folders)
+      move_array, move_element, move_name = dock.find_item(item_query, check_url: true)
+
+      unless move_element
+        $stderr.puts "Error: '#{item_query}' not found in Dock"
+        exit 1
+      end
+
+      # Find the target (check apps first, then folders)
+      after_array, after_element, after_name = dock.find_item(after_target, check_url: true)
+
+      unless after_element
+        $stderr.puts "Error: '#{after_target}' not found in Dock"
+        exit 1
+      end
+
+      # Check if they're the same item
+      if move_element == after_element
+        $stderr.puts "Error: Cannot move an item after itself"
+        exit 1
+      end
+
+      # Check if moving between arrays (apps <-> folders) - not allowed
+      if move_array != after_array
+        $stderr.puts "Error: Cannot move items between apps and folders sections"
+        exit 1
+      end
+
+      # Remove from current position
+      move_array.delete(move_element)
+
+      # Insert after target
+      move_array.insert_after(after_element, move_element)
+
+      dock.save("'#{move_name}' moved after '#{after_name}'.")
+    end
+  end
+end
+
+
+# frozen_string_literal: true
+
+module DockEdit
+  # Command-line interface and option parsing for the `dockedit` executable.
+  #
+  # This class is responsible for parsing global arguments and subcommands and
+  # delegating to the appropriate handlers in {DockEdit::Commands}.
+  class CLI
+    # Build the option parser for the `add` subcommand.
+    #
+    # @param options [Hash] Mutable options hash to be populated by OptionParser.
+    # @return [OptionParser] Configured parser instance.
+    def self.add_parser(options)
+      OptionParser.new do |opts|
+        opts.banner = "Usage: dockedit add [options] <app_or_folder> [...]"
+        opts.separator ""
+        opts.separator "Examples:"
+        opts.separator "  dockedit add Safari Terminal"
+        opts.separator "  dockedit add ~/Downloads --show grid --display stack"
+        opts.separator "  dockedit add --after Safari Notes"
+        opts.separator "  dockedit add ~/Sites --display folder --show grid"
+        opts.on('-a', '--after ITEM', 'Insert after specified app/folder (fuzzy match)') { |app| options[:after] = app }
+        opts.on('--show TYPE', '--view TYPE', 'Folder view: fan/f, grid/g, list/l, auto/a (default: auto)') { |t| options[:show_as] = Parsers.parse_show_as(t) }
+        opts.on('--display TYPE', 'Folder style: folder/f, stack/s (default: folder)') { |t| options[:display_as] = Parsers.parse_display_as(t) }
+      end
+    end
+
+    # Build the option parser for the `space` subcommand.
+    #
+    # @param options [Hash] Mutable options hash to be populated by OptionParser.
+    # @return [OptionParser] Configured parser instance.
+    def self.space_parser(options)
+      OptionParser.new do |opts|
+        opts.banner = "Usage: dockedit space [options]"
+        opts.separator ""
+        opts.separator "Examples:"
+        opts.separator "  dockedit space"
+        opts.separator "  dockedit space --small"
+        opts.separator "  dockedit space --after Safari"
+        opts.separator "  dockedit space --small --after Terminal --after Safari"
+        opts.on('-s', '--small', '--half', 'Insert a small/half-size space') { options[:small] = true }
+        opts.on('-a', '--after APP', 'Insert after specified app (fuzzy match, repeatable)') { |app| options[:after] << app }
+      end
+    end
+
+    # Build the option parser for the `move` subcommand.
+    #
+    # @param options [Hash] Mutable options hash to be populated by OptionParser.
+    # @return [OptionParser] Configured parser instance.
+    def self.move_parser(options)
+      OptionParser.new do |opts|
+        opts.banner = "Usage: dockedit move --after <target> <item_to_move> OR dockedit move <item_to_move> --after <target>"
+        opts.separator ""
+        opts.separator "Examples:"
+        opts.separator "  dockedit move --after Terminal Safari"
+        opts.separator "  dockedit move Safari --after Terminal"
+        opts.on('-a', '--after ITEM', 'Move after specified app/folder (required, fuzzy match)') { |app| options[:after] = app }
+      end
+    end
+
+    # Build the option parser for the `remove` subcommand.
+    #
+    # @param _options [Hash] Present for API symmetry; currently unused.
+    # @return [OptionParser] Configured parser instance.
+    def self.remove_parser(_options = {})
+      OptionParser.new do |opts|
+        opts.banner = "Usage: dockedit remove <app_or_folder> [...]"
+        opts.separator ""
+        opts.separator "Examples:"
+        opts.separator "  dockedit remove Safari Terminal"
+        opts.separator "  dockedit remove ~/Downloads"
+        opts.separator "  dockedit remove --help"
+      end
+    end
+
+    # Build the top-level option parser for the `dockedit` command.
+    #
+    # This parser prints a summary of all subcommands and global options.
+    #
+    # @return [OptionParser]
+    def self.main_parser
+      OptionParser.new do |opts|
+        opts.banner = "Usage: dockedit <subcommand> [options] [args]"
+        opts.separator ""
+        opts.separator "Subcommands:"
+        opts.separator "  add [-a|--after <item>] [--show-as TYPE] <item>...  Add app(s)/folder(s)"
+        opts.separator "  move -a|--after <item> <item>                       Move an item after another"
+        opts.separator "  remove <item>...                                    Remove app(s)/folder(s)"
+        opts.separator "  space [-s|--small] [-a|--after <app>]               Insert space(s)"
+        opts.separator "  help [subcommand]                                   Show help for a subcommand"
+        opts.separator ""
+        opts.separator "Folder shortcuts: desktop, downloads, home, library, documents, applications, sites"
+        opts.separator ""
+        opts.separator "Examples:"
+        opts.separator "  dockedit add Safari Terminal"
+        opts.separator "  dockedit add ~/Downloads --show grid --display stack"
+        opts.separator "  dockedit add Notes --after Safari"
+        opts.separator "  dockedit space --small --after Safari"
+        opts.separator "  dockedit move --after Terminal Safari"
+        opts.separator "  dockedit move Safari --after Terminal"
+        opts.separator "  dockedit help add"
+        opts.separator ""
+        opts.separator "Options:"
+        opts.on('-h', '--help', 'Show this help') do
+          puts opts
+          exit 0
+        end
+      end
+    end
+
+    # Main entry point for the `dockedit` CLI.
+    #
+    # Reads +ARGV+, dispatches to subcommands, and exits with an appropriate
+    # status code.
+    #
+    # @return [void]
+    def self.run
+      global_parser = main_parser
+
+      if ARGV.empty?
+        puts global_parser
+        exit 0
+      end
+
+      subcommand = ARGV.shift
+
+      case subcommand
+      when '-v', '--version'
+        puts DockEdit::VERSION
+        exit 0
+      when 'add'
+        Commands.add(ARGV)
+      when 'move'
+        Commands.move(ARGV)
+      when 'remove'
+        Commands.remove(ARGV)
+      when 'space'
+        Commands.space(ARGV)
+      when 'help', '-h', '--help'
+        help_target = ARGV.shift
+        case help_target
+        when nil
+          puts main_parser
+        when 'add'
+          puts add_parser({})
+        when 'move'
+          puts move_parser({})
+        when 'remove'
+          puts remove_parser({})
+        when 'space'
+          puts space_parser({})
+        else
+          $stderr.puts "Unknown subcommand for help: #{help_target}"
+          $stderr.puts "Valid subcommands: add, move, remove, space"
+          exit 1
+        end
+        exit 0
+      else
+        $stderr.puts "Unknown subcommand: #{subcommand}"
+        $stderr.puts "Run 'dockedit --help' for usage"
+        exit 1
+      end
+    end
+  end
+end
+
+
+
+if __FILE__ == $0
+  DockEdit::CLI.run
+end