dockedit 1.0.0

data/lib/dockedit/app_finder.rb

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

data/lib/dockedit/cli.rb

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

data/lib/dockedit/commands.rb

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

data/lib/dockedit/constants.rb

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