dockedit 1.0.0

data/lib/dockedit/dock.rb

@@ -0,0 +1,98 @@
+# 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
+

data/lib/dockedit/folder_updater.rb

@@ -0,0 +1,58 @@
+# 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
+

data/lib/dockedit/matcher.rb

@@ -0,0 +1,136 @@
+# 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
+

data/lib/dockedit/parsers.rb

@@ -0,0 +1,62 @@
+# 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
+

data/lib/dockedit/path_utils.rb

@@ -0,0 +1,44 @@
+# 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
+

data/lib/dockedit/plist_reader.rb

@@ -0,0 +1,158 @@
+# 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
+

data/lib/dockedit/plist_writer.rb

@@ -0,0 +1,52 @@
+# 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
+