hackmac 1.8.2 → 1.8.3

data/README.md

@@ -1,59 +1,105 @@
-# HackMac
+# HackMac 🚀
 
-## Description
-
-Some ruby tools for working with a Hackintosh, which also might be (partially)
-useful an a regular Mac.
+## Description 📝
 
 HackMac is a set of Ruby tools specifically designed for managing and
 customizing Hackintosh configurations. While primarily intended for users with
 Hackintosh setups, it may also be useful for ordinary Mac users who want to
 leverage its features for monitoring system performance using `gfxmon`.
 
-## Tools
+## Tools 🛠️
 
- - `efi` is a tool to work with OpenCore EFI partitions, that is upgrading
-   OpenCore and Kexts and commiting to its git repository.
- - `usb` can be used to create a bootable USB containing a MacOs release and
-   uses an EFI partition cloned from a git repository.
- - `gfxmon` dispays performance statistics for your AMD GPU in the terminal,
-   that is temperature, clock rate, fan rotations, memory and power usage as
-   provided by MacOS, see the screenshot:
-   ![gfxmon Screenshot](./img/gfxmon.png "gfxmon Screenshot")
+### `efi` - EFI Partition Management 📁
+Manage OpenCore EFI partitions including:
+- Upgrading OpenCore and kernel extensions (kexts) 🔧
+- Committing changes to git repositories 💾
+- Mounting/unmounting EFI volumes 📌
+- Cloning EFI partitions between devices 🔄
 
-## Installation
+### `usb` - Bootable USB Creator 🖥️
+Create bootable USB drives for macOS installation with:
+- Format USB device with GPT partition scheme 📊
+- Create bootable installer using Apple's `createinstallmedia` ⚡
+- Initialize git repository on EFI partition 📦
 
-You can use rubygems to fetch the gem and install it for you:
+### `gfxmon` - GPU Performance Monitor 🎮
+Display real-time performance statistics for your GPU in the terminal including:
+- Temperature, clock rates, fan rotations 🌡️
+- Memory usage and power consumption ⚡
+- Color-coded visualizations with ANSI terminal graphics 🎨
 
-    # gem install hackmac
+![gfxmon Screenshot](./img/gfxmon.png "gfxmon Screenshot")
 
-You can also put this line into your Gemfile
+## Installation 📦
 
-    gem 'hackmac'
+### Using RubyGems 💎
+```bash
+gem install hackmac
+```
 
-# Configuration
+### Using Bundler 📦
+Add to your Gemfile:
+```ruby
+gem 'hackmac'
+```
 
-First start `efi` without arguments this will display the available commands,
-but also initializes a default configuration file in
-`~/.config/hackmac/hackmac.yml` to get you started. If you want work with
-multiple configuration files you can change the path by setting
+## Configuration ⚙️
 
+First run `efi` without arguments to display available commands and initialize
+the default configuration file at:
+```
+~/.config/hackmac/hackmac.yml
 ```
-$ export HACKMAC_CONFIG=~/config/hackmac/other.yml
+
+To use a custom configuration file, set the environment variable:
+```bash
+export HACKMAC_CONFIG=~/config/hackmac/other.yml
 ```
 
-in your shell.
+## Usage Examples 🎯
+
+### EFI Management 📁
+```bash
+# Mount EFI partition
+efi mount
+
+# Clone EFI partitions
+efi clone /dev/disk0s1 /dev/disk1s1
+
+# Upgrade OpenCore
+efi oc_upgrade
 
-## Download
+# Show kext versions
+efi kexts
+```
+
+### GPU Monitoring 🎮
+```bash
+# Real-time monitoring with 2-second updates
+gfxmon -n 2
+
+# Monitor specific metric
+gfxmon -m "Temperature(C)"
+
+# Output as JSON for scripting
+gfxmon -j
+```
+
+### USB Creation 🖥️
+```bash
+# Create bootable USB
+usb /dev/disk2
+```
 
-The homepage of this library is located at
+## Download 🌐
 
-* https://github.com/flori/hackmac
+The homepage of this library is located at:
+https://github.com/flori/hackmac
 
-## Author
+## Author 👨‍💻
 
 [Florian Frank](mailto:flori@ping.de)
 
-## License
+## License 📄
 
-This software is licensed under the MIT license.
+This software is licensed under the [MIT license](LICENSE). ✅

data/Rakefile

@@ -14,6 +14,8 @@ GemHadar do
   test_dir    'tests'
   ignore      '.*.sw[pon]', 'pkg', 'Gemfile.lock', '.rvmrc', '.AppleDouble',
     'tags', '.bundle', '.DS_Store', '.byebug_history'
+  package_ignore '.gitignore', '.contexts'
+
   readme      'README.md'
 
   dependency  'tins',           '~>1.14'
@@ -25,4 +27,6 @@ GemHadar do
   dependency  'search_ui'
   dependency  'hashie'
   development_dependency 'debug'
+
+  licenses << 'MIT'
 end

data/VERSION

@@ -1 +1 @@
-1.8.2
+1.8.3

data/bin/efi

@@ -1,9 +1,41 @@
 #!/usr/bin/env ruby
+#
+# Hackmac EFI Management Tool
+#
+# This script provides comprehensive management capabilities for OpenCore EFI
+# partitions including mounting/unmounting, cloning, kext management, OpenCore
+# upgrades, and git operations.
+#
+# Features:
+#
+# - Mount/Unmount EFI partitions
+# - Clone EFI partitions between devices
+# - Manage kernel extensions (kexts) and their versions
+# - Upgrade OpenCore bootloader to latest versions
+# - Validate OpenCore configurations
+# - Git integration for tracking EFI changes
+#
+# Usage: efi [command] [arguments]
+# Run without arguments to see full help and available commands
+#
+# Configuration:
+# Set HACKMAC_CONFIG to specify a custom config file path
+# Defaults to ~/.config/hackmac/hackmac.yml
 
 require 'hackmac'
 include Hackmac
 include Utils
 
+# The clone method performs a disk cloning operation between two volumes
+#
+# This method facilitates the cloning of data from one disk volume to another
+# by first prompting the user for confirmation, then mounting both volumes,
+# performing a dry-run of the rsync operation to show what would be copied, and
+# finally executing the actual copy with deletion of extraneous files.
+#
+# @param from [ String ] the source disk identifier to clone from
+# @param to [ String ] the target disk identifier to clone to
+# @return [ void ] Returns nothing but performs system disk cloning operations
 def clone(from:, to:)
   ask("Cloning from #{from} to #{to} now? (y/n) ") or return
   x %{sudo mkdir -v "/Volumes/#{from}"}
@@ -18,10 +50,18 @@ def clone(from:, to:)
   x %{rsync -av --exclude ".*" --delete "/Volumes/#{from}/" "/Volumes/#{to}/"}
 end
 
+# The usage method displays help information and command usage instructions
+#
+# This method outputs a formatted help message that describes the available
+# commands and their arguments for the Hackmac tool. It provides default device
+# names
+# and explains how to configure the tool using environment variables.
+#
+# @return [ void ] Returns nothing but prints usage information to standard output
 def usage
   default_dev = device_name('main')
 
-  puts <<~end
+  puts <<~EOT
 
     Usage #{File.basename($0)} [command] [arguments]
 
@@ -88,11 +128,21 @@ def usage
         Commits changes with git, passes arguments to commit command
         after "--".
 
-  end
+  EOT
 end
 
-$config = Hackmac::Config.load
-
+# The device_name method determines the appropriate device name based on the
+# provided mount device identifier
+#
+# This method retrieves the device name by checking if a mount device
+# identifier is provided. If no identifier is given, it returns the main device
+# name from the configuration. If an identifier is provided, it looks up the
+# corresponding device in the configuration and returns its name, falling back
+# to the original identifier if not found
+#
+# @param mdev [ String, nil ] the mount device identifier to look up, or nil to use the main device
+#
+# @return [ String ] the resolved device name from configuration or the original identifier
 def device_name(mdev)
   case mdev
   when nil
@@ -106,6 +156,16 @@ def device_name(mdev)
   end
 end
 
+# The git_args method processes command line arguments to determine the device
+# name and default git arguments
+#
+# This method handles the parsing of command line arguments for git operations,
+# identifying whether a device name is provided and managing the default
+# arguments that should be used when none are specified
+#
+# @param default [ Array<String> ] the default git arguments to use when none are provided
+#
+# @return [ String ] the device name determined from the command line arguments
 def git_args(default:)
   mdev =
     if ARGV.first == '--'
@@ -120,22 +180,19 @@ def git_args(default:)
   mdev
 end
 
+$config = Hackmac::Config.load
+
 bold_head = -> h { h.sub(/\A[a-z]/) { $&.upcase }.bold }
 
 case command = ARGV.shift
 when 'help', nil
   usage
 when 'mount'
-  #if File.exist?('/Volumes/EFI')
-  #  raise "/Volumes/EFI already exists => Sort this out first."
-  #end
   mdev = device_name(ARGV.shift)
   x %{sudo diskutil mount "#{mdev}"}
-  # TODO symlink to /Volumes/mdev, mdev should be foo['MountPoint'] from efi boot
 when /\Aun?mount\z/
   mdev = device_name(ARGV.shift)
   x %{sudo diskutil unmount "#{mdev}"}
-  # TODO remove /Volumes/mdev if it is a symlink
 when /\Adiff\z/
   mdev = git_args(default: %w[ --color --stat --cached ])
   x %{sudo diskutil mount "#{mdev}"}
@@ -161,9 +218,11 @@ when 'clone'
 when 'kexts'
   mdev = device_name(ARGV.shift)
   x %{sudo diskutil mount "#{mdev}"}
-  on_efi = Dir["/Volumes/#{mdev}/#{$config.kext.efi_path}/*.kext"].map { |path|
+  on_efi = Dir["/Volumes/#{mdev}/#{$config.kext.efi_path}/*.kext"].map do |path|
     Kext.new(path: path, config: $config)
-  }.sort_by(&:name)
+  rescue Errno::ENOENT
+    warn  "#{path.to_s.inspect} has no info => Skipping."
+  end.compact.sort_by(&:name)
   puts 'EFI'.yellow.bold + " (#{mdev})".bold
   puts Tabulo::Table.new(on_efi, align_header: :left, border: :modern) { |t|
     t.add_column(:name, header_styler: bold_head)

data/bin/gfxmon

@@ -1,4 +1,23 @@
 #!/usr/bin/env ruby
+#
+# GPU Performance Monitor
+#
+# A terminal-based tool for monitoring and visualizing GPU performance metrics
+# in real-time. Displays system hardware statistics including temperature,
+# clock speeds, memory usage, and power consumption with graphical
+# representations.
+#
+# Features:
+# - Real-time monitoring with customizable update intervals
+# - Color-coded visualizations using ANSI terminal graphics
+# - Support for multiple metric types (bytes, hertz, celsius, percentage)
+# - Interactive search for performance metrics
+# - JSON output support for integration with other tools
+#
+# Example:
+#   gfxmon                     # Real-time graph with metrics
+#   gfxmon -n 3                # Update every 3 seconds
+#   gfxmon -m "Temperature(C)" # Show specific metric
 
 require 'tins'
 include Tins::GO
@@ -16,8 +35,15 @@ include SearchUI
 
 $opts = go 'c:m:n:jlh', defaults: { ?s => true, ?n => 5 }
 
+# The usage method displays command-line usage information and options
+#
+# This method prints a formatted help message to the standard output that
+# describes how to use the command-line tool, including available options
+# and their descriptions for controlling GPU performance data output
+#
+# @return [ Integer ] always returns 0 to indicate successful help display
 def usage
-  puts <<~end
+  puts <<~EOT
   Usage: #{File.basename($0)} [OPTIONS]
 
     OPTIONS are
@@ -29,14 +55,30 @@ def usage
       -m METRIC   output graph for performance METRIC
       -c COLOR    output graph in this terminal COLOR (between 0 - 255)
 
-  end
+  EOT
   0
 end
 
+# The ps method retrieves performance statistics from the IORegistry
+#
+# This method accesses the PerformanceStatistics key in the IORegistry
+# to obtain detailed hardware performance data and returns it as a hash
+#
+# @return [ Hash ] a hash containing the performance statistics data from the
+#   IORegistry
 def ps
   Hackmac::IOReg.new(key: 'PerformanceStatistics').as_hash
 end
 
+# The list method displays a formatted key-value pair listing with colored
+# output
+#
+# This method takes a hash of key-value pairs and formats them for display in
+# the terminal, applying color coding to the keys and formatting the values
+# according to derived formatters. It sorts the entries by key before
+# displaying them.
+#
+# @param ps [ Hash ] a hash containing string keys and numeric or string values to be displayed
 def list(ps)
   max = ps.keys.max_by(&:size)&.size&.to_i
   include Hackmac::Graph::Formatters
@@ -46,6 +88,21 @@ def list(ps)
   }
 end
 
+# The choose_metric method selects a metric from a provided hash based on user
+# input or configuration
+#
+# This method attempts to determine the appropriate metric to use by first
+# checking for a configured metric in the global options. If no metric is
+# configured, it prompts the user to select from available metrics using an
+# interactive search interface. The method validates that the selected metric
+# exists in the provided hash and raises an error if the metric is not
+# recognized.
+#
+# @param ps [ Hash ] a hash containing available metric names as keys
+#
+# @return [ String ] the name of the selected metric
+#
+# @raise [ RuntimeError ] if the specified metric is not found in the provided hash
 def choose_metric(ps)
   case metric = $opts[?m]
   when nil
@@ -73,6 +130,16 @@ def choose_metric(ps)
   fail "Metric #{metric} not known"
 end
 
+# The derive_formatter method maps a metric string to an appropriate formatting
+# method symbol
+#
+# This method takes a metric identifier string and determines the corresponding
+# formatting strategy by matching against common metric patterns such as bytes,
+# hertz, celsius, and percentage values
+#
+# @param metric [ String ] the metric identifier to derive formatting from
+#
+# @return [ Symbol ] the appropriate formatter method symbol for the given metric
 def derive_formatter(metric)
   case metric
   when /bytes/i
@@ -88,6 +155,18 @@ def derive_formatter(metric)
   end
 end
 
+# The display_graph method creates and starts a graphical representation of
+# system metrics
+#
+# This method initializes a graph visualization based on selected system
+# metrics, configuring the display with appropriate formatting, color settings,
+# and update intervals before beginning the continuous rendering process
+#
+# @return [ void ] Returns nothing but initiates the graphical display loop for system metrics
+#
+# @see Hackmac::Graph
+# @see choose_metric
+# @see derive_formatter
 def display_graph
   if metric = choose_metric(ps)
     sleep_duration = [ 1, ($opts[?n] || 10).to_i ].max

data/bin/usb

@@ -1,17 +1,41 @@
 #!/usr/bin/env ruby
+#
+# USB Installer Script
+#
+# This script prepares a USB drive for macOS installation by:
+# - Formatting the USB device with GPT partition scheme
+# - Creating a bootable installer using Apple's createinstallmedia tool
+# - Mounting the EFI partition and initializing a git repository
+#
+# Example: usb /dev/disk2
+#
+# Requirements:
+# - USB device must be at least 16GB
+# - macOS installer package must be present in config
+# - User must have administrator privileges
+#
+# Environment Variables:
+#   HACKMAC_CONFIG - Path to configuration file (default: ~/.config/hackmac/config.yml)
+#
+# This script performs destructive operations and should be used with caution.
 
 require 'hackmac'
 include Hackmac
 include Utils
 
+# The usage method displays help information and exits the program
+#
+# This method prints a usage message to the standard output that includes
+# the command name and available options, then terminates execution with
+# a status code of 1
 def usage
-  puts <<~end
+  puts <<~EOT
 
     Usage #{File.basename($0)} [USB DEVICE]
 
     Set HACKMAC_CONFIG to the config file, e. g. ~/.config/hackmac/foobar.yml
 
-  end
+  EOT
   exit 1
 end
 

data/hackmac.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: hackmac 1.8.2 ruby lib
+# stub: hackmac 1.8.3 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "hackmac".freeze
-  s.version = "1.8.2".freeze
+  s.version = "1.8.3".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -13,15 +13,16 @@ Gem::Specification.new do |s|
   s.email = "flori@ping.de".freeze
   s.executables = ["efi".freeze, "gfxmon".freeze, "usb".freeze]
   s.extra_rdoc_files = ["README.md".freeze, "lib/hackmac.rb".freeze, "lib/hackmac/asset_tools.rb".freeze, "lib/hackmac/config.rb".freeze, "lib/hackmac/disks.rb".freeze, "lib/hackmac/github_source.rb".freeze, "lib/hackmac/graph.rb".freeze, "lib/hackmac/graph/display.rb".freeze, "lib/hackmac/ioreg.rb".freeze, "lib/hackmac/kext.rb".freeze, "lib/hackmac/kext_upgrader.rb".freeze, "lib/hackmac/oc.rb".freeze, "lib/hackmac/oc_upgrader.rb".freeze, "lib/hackmac/oc_validator.rb".freeze, "lib/hackmac/plist.rb".freeze, "lib/hackmac/url_download.rb".freeze, "lib/hackmac/utils.rb".freeze, "lib/hackmac/version.rb".freeze]
-  s.files = [".gitignore".freeze, "CHANGES.md".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "VERSION".freeze, "bin/efi".freeze, "bin/gfxmon".freeze, "bin/usb".freeze, "hackmac.gemspec".freeze, "img/gfxmon.png".freeze, "lib/hackmac.rb".freeze, "lib/hackmac/asset_tools.rb".freeze, "lib/hackmac/config.rb".freeze, "lib/hackmac/disks.rb".freeze, "lib/hackmac/github_source.rb".freeze, "lib/hackmac/graph.rb".freeze, "lib/hackmac/graph/display.rb".freeze, "lib/hackmac/hackmac.yml".freeze, "lib/hackmac/ioreg.rb".freeze, "lib/hackmac/kext.rb".freeze, "lib/hackmac/kext_upgrader.rb".freeze, "lib/hackmac/oc.rb".freeze, "lib/hackmac/oc_upgrader.rb".freeze, "lib/hackmac/oc_validator.rb".freeze, "lib/hackmac/plist.rb".freeze, "lib/hackmac/url_download.rb".freeze, "lib/hackmac/utils.rb".freeze, "lib/hackmac/version.rb".freeze]
+  s.files = [".context/code_comment.rb".freeze, "CHANGES.md".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "VERSION".freeze, "bin/efi".freeze, "bin/gfxmon".freeze, "bin/usb".freeze, "hackmac.gemspec".freeze, "img/gfxmon.png".freeze, "lib/hackmac.rb".freeze, "lib/hackmac/asset_tools.rb".freeze, "lib/hackmac/config.rb".freeze, "lib/hackmac/disks.rb".freeze, "lib/hackmac/github_source.rb".freeze, "lib/hackmac/graph.rb".freeze, "lib/hackmac/graph/display.rb".freeze, "lib/hackmac/hackmac.yml".freeze, "lib/hackmac/ioreg.rb".freeze, "lib/hackmac/kext.rb".freeze, "lib/hackmac/kext_upgrader.rb".freeze, "lib/hackmac/oc.rb".freeze, "lib/hackmac/oc_upgrader.rb".freeze, "lib/hackmac/oc_validator.rb".freeze, "lib/hackmac/plist.rb".freeze, "lib/hackmac/url_download.rb".freeze, "lib/hackmac/utils.rb".freeze, "lib/hackmac/version.rb".freeze]
   s.homepage = "http://github.com/flori/hackmac".freeze
+  s.licenses = ["MIT".freeze]
   s.rdoc_options = ["--title".freeze, "Hackmac - Some useful tools for working with a Hackintosh".freeze, "--main".freeze, "README.md".freeze]
   s.rubygems_version = "3.6.9".freeze
   s.summary = "Some useful tools for working with a Hackintosh".freeze
 
   s.specification_version = 4
 
-  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 1.20".freeze])
+  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 2.6".freeze])
   s.add_development_dependency(%q<debug>.freeze, [">= 0".freeze])
   s.add_runtime_dependency(%q<tins>.freeze, ["~> 1.14".freeze])
   s.add_runtime_dependency(%q<term-ansicolor>.freeze, ["~> 1.10".freeze])

data/lib/hackmac/asset_tools.rb

@@ -1,7 +1,35 @@
 module Hackmac
+  # A module that provides utility methods for creating temporary directories
+  # and decompressing files.
+  #
+  # The AssetTools module offers helper methods designed to simplify common
+  # tasks when working with temporary file operations and compressed assets. It
+  # includes functionality for isolating code execution within temporary
+  # directories and extracting various compressed file formats.
+  #
+  # @example
+  #   include Hackmac::AssetTools
+  #
+  #   isolate do |dir|
+  #     # Code executed within temporary directory
+  #   end
+  #
+  #   decompress('archive.tar.gz')
   module AssetTools
     private
 
+    # The isolate method creates a temporary directory and yields control to a
+    # block within that directory context.
+    #
+    # This method establishes a temporary working directory using Dir.mktmpdir,
+    # changes the current working directory to that location, and then executes
+    # the provided block within that context. After the block completes, it
+    # ensures proper cleanup of the temporary directory.
+    #
+    # @param block [ Block ] the block to execute within the temporary
+    # directory context
+    #
+    # @return [ Object ] the return value of the yielded block
     def isolate
       Dir.mktmpdir do |dir|
         cd dir do
@@ -10,6 +38,20 @@ module Hackmac
       end
     end
 
+    # The decompress method extracts compressed files in either ZIP or tar.gz
+    # format
+    #
+    # This method takes a filename and attempts to decompress it using the
+    # appropriate system command based on the file extension. It provides
+    # visual feedback during the decompression process and raises an error if
+    # the operation fails.
+    #
+    # @param name [ String ] the path to the compressed file to be decompressed
+    #
+    # @return [ void ] Returns nothing, but performs system decompression operations
+    #
+    # @raise [ RuntimeError ] raised when the file extension is not supported or
+    #                         decompression commands fail
     def decompress(name)
       print "Decompressing #{name.inspect}…"
       case name
@@ -22,6 +64,5 @@ module Hackmac
       end
       puts "done!"
     end
-
   end
 end

data/lib/hackmac/config.rb

@@ -5,6 +5,22 @@ require 'pathname'
 require 'term/ansicolor'
 
 module Hackmac
+  # A module that provides configuration loading and management functionality
+  # for Hackmac
+  #
+  # The Config module handles the initialization and retrieval of Hackmac's
+  # configuration settings from specified files or default locations. It
+  # manages configuration directories, creates default configuration files when
+  # needed, and loads configurations into memory for use throughout the
+  # application.
+  #
+  # @example
+  #   Hackmac::Config.load
+  #   # Loads the default configuration file
+  #
+  # @example
+  #   Hackmac::Config.load(path: '/custom/config/path.yml')
+  #   # Loads a custom configuration file from the specified path
   module Config
     extend FileUtils
     extend ComplexConfig::Provider::Shortcuts
@@ -12,6 +28,22 @@ module Hackmac
 
     DEFAULT = File.read(File.join(File.dirname(__FILE__), 'hackmac.yml'))
 
+    # Loads the Hackmac configuration from the specified path or default
+    # location
+    #
+    # This method initializes the configuration system by reading from a
+    # specified file path or using the default configuration file location. It
+    # ensures the configuration directory exists, sets up the configuration
+    # provider's directory, creates a default configuration file if one doesn't
+    # exist, and loads the configuration into memory for use throughout the
+    # application.
+    #
+    # @param path [ String ] the file path to load the configuration from, defaults
+    #   to the value of the HACKMAC_CONFIG environment variable or the default
+    #   location ~/.config/hackmac/hackmac.yml
+    #
+    # @return [ ComplexConfig::Provider ] the loaded configuration provider object
+    #   that can be used to access configuration values
     def self.load(path: ENV.fetch('HACKMAC_CONFIG', '~/.config/hackmac/hackmac.yml'))
       path = Pathname.new(path).expand_path
       mkdir_p path.dirname