kanseishitsu 0.1.1

data/lib/kanseishitsu/launch_agent_manager.rb

@@ -0,0 +1,224 @@
+# encoding: utf-8
+# frozen_string_literal: false
+
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+# Copyright Nels Nelson 2024 but freely usable (see license)
+
+require 'nokogiri'
+
+require 'fileutils'
+
+require_relative 'launch_agent_constants'
+require_relative 'logging'
+require_relative 'which'
+require_relative 'xml_helper'
+
+# Define module LaunchAgentManagementInstanceMethods
+module LaunchAgentManagementInstanceMethods
+  include LaunchAgentConstants
+  include Which
+
+  # Extract program path and arguments, verifying executable
+  # rubocop: disable Metrics/MethodLength
+  def extract_program_path(executable_with_args)
+    *args = if executable_with_args.respond_to?(:split)
+      executable_with_args.split
+    else
+      executable_with_args
+    end
+    exe_path = which(args.shift)
+    if exe_path.nil? || !File.exist?(exe_path)
+      abort "Cannot find executable in path: #{exe_path}"
+    end
+    if exe_path.nil? || !File.executable?(exe_path) || File.directory?(exe_path)
+      abort "Given file is not executable: #{exe_path}"
+    end
+    args.unshift(exe_path)
+    args
+  end
+  # rubocop: enable Metrics/MethodLength
+
+  # Create the job name based on the given file path
+  def derive_job_label_from_file_path(file_path)
+    label = LABEL_NAMESPACE.dup
+    label << File.basename(file_path, '.*')
+    label.join('.')
+  end
+
+  # Define cron settings for plist
+  def define_calendar_interval(cron_schedule)
+    cron_fields = cron_schedule.split
+    calendar_interval = {}
+    INTERVALS.each do |key|
+      value = cron_fields.shift
+      raise "Invalid cron string: #{cron_schedule}" if value.nil? || value.empty?
+
+      calendar_interval[key] = value
+    end
+    calendar_interval
+  end
+
+  # Define the plist contents
+  # rubocop: disable Metrics/MethodLength
+  def define_plist_contents(label, args, cron_schedule)
+    definition = {}
+    definition['Label'] = label
+    definition['StartCalendarInterval'] = define_calendar_interval(cron_schedule)
+    unless (system_path = ENV.fetch('PATH', nil)).nil? || system_path.empty?
+      definition['EnvironmentVariables'] = {}
+      definition['EnvironmentVariables']['PATH'] = system_path
+    end
+    if args.length == 1
+      definition['Program'] = args.first
+    else
+      definition['ProgramArguments'] = args
+    end
+    definition
+  end
+  # rubocop: enable Metrics/MethodLength
+
+  # Save plist file to LaunchAgents directory; do not overwrite an
+  # already existing file with the same name at the generated path
+  def save_plist(label, doc)
+    FileUtils.mkdir_p(LAUNCH_AGENTS_DIR_PATH)
+    plist_path = File.join(LAUNCH_AGENTS_DIR_PATH, "#{label}.plist")
+    return plist_path if File.exist?(plist_path)
+
+    log.debug "Contents of plist xml document:\n#{doc.to_xml}"
+    File.write(plist_path, doc.to_xml)
+    plist_path
+  end
+
+  def execute(command)
+    log.debug "Executing command: #{command}"
+    system(command)
+  end
+
+  # Load the launchd job
+  def load_launchd_job(plist_path)
+    execute(format(LAUNCHCTL_TEMPLATE, uid: Process.uid, plist: plist_path))
+  end
+
+  def doctype
+    format(DOCTYPE_ELEMENT, doctypes: DOCTYPES.join(' '))
+  end
+
+  # Use Nokogiri to create a launchd plist XML document
+  def generate_plist_xml(definition_hash)
+    doc = Nokogiri::XML(doctype)
+    doc.encoding = DEFAULT_ENCODING
+    plist = doc.create_element('plist', version: '1.0')
+    root = doc.create_element('dict')
+
+    definition_hash.each do |key, value|
+      create_xml_tag(doc, root, key, value)
+    end
+
+    plist << root
+    doc << plist
+    doc
+  end
+
+  # Return a list of all user launch agent labels
+  def launch_agent_labels
+    labels = []
+
+    Dir.glob(File.join(LAUNCH_AGENTS_DIR_PATH, '*.plist')).each do |file_path|
+      doc = File.open(file_path) { |file| Nokogiri::XML(file) }
+      label_node = doc.xpath(LABEL_XPATH)
+      labels << label_node.text unless label_node.empty?
+    end
+
+    labels
+  end
+
+  # Parse the calendar interval
+  def parse_schedule(doc)
+    watch_paths_node = doc.xpath(WATCH_PATHS_XPATH)
+    watch_paths = watch_paths_node.xpath(LOCAL_STRING_XPATH).map(&:text)
+    return watch_paths.first unless watch_paths.empty?
+
+    intervals = doc.xpath(START_CALENDAR_INTERVAL_XPATH).first
+    return ON_LOGIN unless intervals
+
+    INTERVALS.map do |interval|
+      xpath = format(INTERVAL_XPATH_TEMPLATE, key: interval)
+      intervals.at_xpath(xpath).text rescue '*'
+    end.join(' ')
+  end
+
+  # Function to parse plist and extract crontab-like schedule
+  # rubocop: disable Metrics/AbcSize
+  # rubocop: disable Metrics/MethodLength
+  def parse_plist(plist_path)
+    plist = {}
+    doc = Nokogiri::XML(File.read(plist_path))
+    label = doc.xpath(LABEL_XPATH).text
+    watch_paths = doc.xpath(WATCH_PATHS_XPATH).xpath(LOCAL_STRING_XPATH).map(&:text)
+    program_args = doc.xpath(PROGRAM_ARGUMENTS_XPATH).xpath(LOCAL_STRING_XPATH).map(&:text)
+    schedule = parse_schedule(doc)
+    plist[:label] = label unless label.nil?
+    plist[:command] = program_args.empty? ? label : program_args.join(' ')
+    plist[:watch_paths] = watch_paths unless watch_paths.nil?
+    plist[:schedule] = schedule unless schedule.nil?
+    plist
+  end
+  # rubocop: enable Metrics/AbcSize
+  # rubocop: enable Metrics/MethodLength
+
+  # Show the relevant launch agents
+  def show_all_launch_agents
+    Dir.glob(File.join(LAUNCH_AGENTS_DIR_PATH, '*.plist')).map do |plist_path|
+      job = parse_plist(plist_path)
+      puts "#{job[:schedule]} #{job[:command]}"
+    end
+  end
+
+  # List labels of launch agents
+  def list_launch_agent_labels
+    launch_agent_labels.each do |label|
+      puts label
+    end
+  end
+
+  # Remove plist Launch Agents by label
+  # rubocop: disable Metrics/MethodLength
+  def remove_launch_agent(label)
+    log.debug "Removing launch agent: #{label}"
+    plist_path = File.expand_path(File.join(LAUNCH_AGENTS_DIR_PATH, "#{label}.plist"))
+    log.debug "Removing launch agent plist definition file: #{plist_path}"
+    if File.exist?(plist_path)
+      execute(format(BOOTOUT_TEMPLATE, uid: Process.uid, label: label))
+      execute(format(REMOVE_TEMPLATE, uid: Process.uid, label: label))
+      FileUtils.rm(plist_path)
+      puts "Removed launch agent: #{label}"
+    else
+      warn "Not found; crontab or launch agent: #{label}"
+    end
+  end
+  # rubocop: enable Metrics/MethodLength
+
+  # Create a file monitor launch agent
+  def create_launch_agent(exe, exe_path, schedule)
+    args = extract_program_path(exe)
+    label = derive_job_label_from_file_path(exe_path || args.first)
+    definition = define_plist_contents(label, args, schedule)
+    doc = generate_plist_xml(definition)
+    plist_path = save_plist(label, doc)
+    load_launchd_job(plist_path)
+    puts format(SUCCESS_MESSAGE, label: label)
+  end
+end
+# module LaunchAgentManagementInstanceMethods
+
+# Define class LaunchAgentManager
+class LaunchAgentManager
+  include LaunchAgentManagementInstanceMethods
+  include XMLHelperInstanceMethods
+
+  def initialize(options)
+    @options = options
+  end
+end

data/lib/kanseishitsu/logging.rb

@@ -0,0 +1,49 @@
+# encoding: utf-8
+# frozen_string_literal: false
+
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+# Copyright Nels Nelson 2024 but freely usable (see license)
+
+require 'logger'
+require 'syslog/logger'
+
+# Define class MultiLogger
+class MultiLogger
+  def initialize(invoking_class)
+    @invoking_class = invoking_class
+  end
+
+  %i[info warn debug error fatal].each do |method|
+    define_method(method) do |message|
+      MultiLogger.loggers.each do |logger|
+        logger.add(Logger.const_get(method.upcase), message, @invoking_class || 'Unknown')
+      end
+    end
+  end
+
+  def log_level=(level)
+    MultiLogger.loggers.each { |logger| logger.level = level }
+  end
+
+  def self.loggers
+    @loggers ||= begin
+      stdout_logger = Logger.new($stdout)
+      stdout_logger.level = Logger::INFO
+      stdout_logger.formatter = proc do |severity, datetime, progname, msg|
+        "#{datetime} #{severity} [#{progname}] #{msg}\n"
+      end
+      syslog_logger = Syslog::Logger.new(PROJECT)
+      syslog_logger.level = Logger::INFO
+      [stdout_logger, syslog_logger]
+    end
+  end
+end
+
+# Re-open class Object
+class Object
+  def log
+    @log ||= MultiLogger.new(self.class.name)
+  end
+end

data/lib/kanseishitsu/plist_parser.rb

@@ -0,0 +1,110 @@
+# encoding: utf-8
+# frozen_string_literal: false
+
+# vi: set ft=ruby :
+# -*- mode: ruby -*-
+
+# Copyright Nels Nelson 2024 but freely usable (see license)
+
+require 'rexml/document'
+
+require_relative 'cron'
+
+# Define the PlistParser class
+# class PlistParser
+#   LOCAL_STRING_XPATH = './string'.freeze
+#   PROGRAM_ARGUMENTS_XPATH =
+#     '//key[text()="ProgramArguments"]/following-sibling::array[1]'.freeze
+#   LABEL_XPATH = '//key[text()="Label"]/following-sibling::*[1]'.freeze
+#   CALENDAR_XPATH = '//key[text()="StartCalendarInterval"]/following-sibling::*[1]'.freeze
+#   SCHEDULE_XPATH_TEMPLATE = './/key[text()="%<key>s"]/following-sibling::integer'.freeze
+#   ON_LOGIN = '@login'.freeze
+
+#   # Parse the Plist file at the given path
+#   def parse(plist_path)
+#     plist = {}
+#     doc = REXML::Document.new(File.read(plist_path))
+#     label = parse_plist_label(doc)
+#     command = parse_program_arguments(doc, label)
+#     cron_schedule = parse_calendar_interval(doc)
+#     plist[:label] = label unless label.nil?
+#     plist[:command] = command unless command.nil?
+#     plist[:schedule] = cron_schedule unless cron_schedule.nil?
+#     plist
+#   end
+
+#   # Parse the label from the Plist file document
+#   def parse_plist_label(doc)
+#     label_element = REXML::XPath.first(doc, LABEL_XPATH)
+#     return nil if label_element.nil?
+
+#     label = label_element.text
+#     return nil if label.empty?
+
+#     label
+#   end
+
+#   # Parse the program arguments from the Plist file document
+#   def parse_program_arguments(doc, label)
+#     program_args_elements = REXML::XPath.match(doc, PROGRAM_ARGUMENTS_XPATH)
+#     program_args = program_args_elements.flat_map do |node|
+#       REXML::XPath.match(node, LOCAL_STRING_XPATH).map(&:text)
+#     end
+#     program_args.empty? ? label : program_args.join(' ')
+#   end
+
+#   # Parse the calendar interval from the Plist file document
+#   def parse_calendar_interval(doc)
+#     intervals = doc.xpath(CALENDAR_XPATH).first
+#     return ON_LOGIN unless intervals
+
+#     Cron::INTERVALS.map do |interval|
+#       intervals.at_xpath(format(SCHEDULE_XPATH_TEMPLATE, key: interval)).text rescue '*'
+#     end.join(' ')
+#   end
+# end
+
+# Define class PlistParser
+class PlistParser
+  EMPTY_STRING = ''.freeze
+
+  def initialize(file_path)
+    @file_path = file_path
+  end
+
+  def parse
+    xml = File.read(@file_path)
+    document = REXML::Document.new(xml)
+    plist = parse_element(document.root.elements[1]) # the root <dict> inside <plist>
+    LaunchAgentPlist.new(
+      plist['Label'],
+      plist['ProgramArguments'],
+      plist['StartInterval'] || plist['CalendarStartInterval']
+    )
+  end
+
+  private
+
+  def parse_element(element)
+    case element.name.to_sym
+    when :dict then parse_dict(element)
+    when :array then parse_array(element)
+    when :string then element.text || EMPTY_STRING
+    end
+  end
+
+  def parse_dict(dict_element)
+    dict = {}
+    dict_element.elements.each_slice(2) do |key, value|
+      dict[key.text] = parse_element(value)
+    end
+    dict
+  end
+
+  def parse_array(array_element)
+    array_element.elements.map do |element|
+      parse_element(element)
+    end
+  end
+end
+# class PlistParser

data/lib/kanseishitsu/version.rb

@@ -0,0 +1,11 @@
+# encoding: utf-8
+# frozen_string_literal: false
+
+# vi: set ft=ruby :
+# -*- mode: ruby -*-
+
+# Copyright Nels Nelson 2024 but freely usable (see license)
+
+module Kanseishitsu
+  VERSION = '0.1.1'.freeze
+end

data/lib/kanseishitsu/watch/argument_parser.rb

@@ -0,0 +1,138 @@
+# encoding: utf-8
+# frozen_string_literal: false
+
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+# Copyright Nels Nelson 2024 but freely usable (see license)
+
+require 'optparse'
+
+require_relative '../which'
+require_relative '../version'
+
+# Define module Watcher
+module Watcher
+  # Define the ArgumentsParser class
+  class ArgumentsParser
+    UNDERSCORE_PATTERN = %r{_}
+    HYPHEN_STRING = '-'.freeze
+    FLAGS = %i[banner show_all list remove verbose].freeze
+    POSITIONAL = %i[watch_path executable_path_with_args].freeze
+    attr_reader :parser, :options
+
+    def initialize(parser = OptionParser.new)
+      @parser = parser
+      @options = {}
+      FLAGS.each { |method_name| self.method(method_name).call }
+    end
+
+    def banner
+      @parser.banner = "Usage: #{File.basename($PROGRAM_NAME)} " \
+        '<watch_path> <executable_path_with_args>'
+      @parser.separator ''
+      @parser.separator 'Options:'
+    end
+
+    def show_all
+      @parser.on('--show-all', 'Show watchers') do
+        @options[:show_all] = true
+      end
+    end
+
+    def list
+      @parser.on('-l', '--list', 'List watcher labels') do
+        @options[:list] = true
+      end
+    end
+
+    def remove
+      @parser.on('-r', '--remove=<label>', 'Remove a watcher by label') do |label|
+        @options[:remove] = label
+      end
+    end
+
+    def verbose
+      @options[:log_level] ||= Logger::INFO
+      @parser.on_tail('-v', '--verbose', 'Increase verbosity') do
+        @options[:log_level] -= 1
+      end
+    end
+
+    def version
+      @parser.on_tail('--version', 'Show version') do
+        puts "#{File.basename($PROGRAM_NAME)} version #{Kanseishitsu::VERSION}"
+        exit
+      end
+    end
+
+    def watch_path(args)
+      return if (v = args.shift).nil?
+
+      watch_path = File.expand_path(v)
+      unless File.exist?(watch_path) &&
+          File.directory?(watch_path)
+        message = "Directory not found: #{watch_path}"
+        raise OptionParser::InvalidArgument, message
+      end
+      @options[:watch_path] = [watch_path]
+    end
+
+    def executable_path_with_args(args)
+      executable, *args = args
+      return if executable.nil?
+
+      executable_path = Object.new.extend(Which).which(executable)
+      if executable_path.nil?
+        message = "Executable not found: #{executable_path}"
+        raise OptionParser::InvalidArgument, message
+      end
+      @options[:executable_path_with_args] = [executable_path] + args
+    end
+
+    def demand(arg, positional: false)
+      return @options[arg] unless @options[arg].nil?
+
+      required_arg = if positional then "<#{arg}>"
+      else "--#{arg.to_s.gsub(UNDERSCORE_PATTERN, HYPHEN_STRING)}"
+      end
+      raise OptionParser::MissingArgument, "Required argument: #{required_arg}"
+    end
+
+    def positional!(args)
+      POSITIONAL.each do |opt|
+        self.method(opt).call(args)
+        self.demand(opt, positional: true)
+      end
+    end
+
+    def options?
+      ArgumentsParser::FLAGS.any? { |flag| @options.include?(flag) }
+    end
+
+    def usage!
+      puts @parser
+      exit
+    end
+
+    # rubocop: disable Metrics/MethodLength
+    def self.parse(args = ARGV, _file_path = ARGF, arguments_parser = ArgumentsParser.new)
+      arguments_parser.parser.parse!(args)
+      if !arguments_parser.options? && ARGV.length != 2
+        message = 'A directory and executable handler is required'
+        raise OptionParser::MissingArgument, message
+      elsif !args.empty?
+        arguments_parser.positional!(args)
+      end
+      arguments_parser.options
+    rescue OptionParser::AmbiguousOption => e
+      abort e.message
+    rescue OptionParser::ParseError => e
+      puts e.message
+      arguments_parser.usage!
+    end
+    # rubocop: enable Metrics/MethodLength
+  end
+  # class ArgumentsParser
+end
+# module Watcher

data/lib/kanseishitsu/watch.rb

@@ -0,0 +1,90 @@
+#! /usr/bin/env ruby
+# encoding: utf-8
+# frozen_string_literal: false
+
+# vi: set ft=ruby :
+# -*- mode: ruby -*-
+
+# Copyright Nels Nelson 2024 but freely usable (see license)
+
+# Usage: watch.rb <path> [handler_program_path]
+#
+# Options:
+#         --show-all                   Show watchers
+#     -l, --list                       List launch agent labels
+#     -r, --remove=<label>             Remove a watcher by label
+#
+# Examples:
+#
+# watch.rb ~/Desktop ~/.local/usr/bin/desktop.rb
+# watch.rb --show-all
+# watch.rb --list
+# watch.rb --remove=com.local.desktop
+
+require_relative 'launch_agent_manager'
+require_relative 'watch/argument_parser'
+
+# Define module Watcher
+module Watcher
+  # Define class LaunchAgentManager
+  class LaunchAgentManager < ::LaunchAgentManager
+    # Define the plist contents
+    # rubocop: disable Metrics/MethodLength
+    def define_plist_contents(label, args, *watch_paths)
+      definition = {}
+      definition['Label'] = label
+      definition['WatchPaths'] = watch_paths
+      unless (system_path = ENV.fetch('PATH', nil)).nil? || system_path.empty?
+        definition['EnvironmentVariables'] = {}
+        definition['EnvironmentVariables']['PATH'] = system_path
+      end
+      if args.length == 1
+        definition['Program'] = args.first
+      else
+        definition['ProgramArguments'] = args
+      end
+      definition
+    end
+    # rubocop: enable Metrics/MethodLength
+
+    # Return a list of all user launch agent labels
+    def launch_agent_labels
+      labels = []
+
+      Dir.glob(File.join(LAUNCH_AGENTS_DIR_PATH, '*.plist')).each do |file_path|
+        doc = File.open(file_path) { |file| Nokogiri::XML(file) }
+        watch_paths = doc.xpath(WATCH_PATHS_XPATH)
+        next if watch_paths.nil? || watch_paths.empty?
+
+        label_node = doc.xpath(LABEL_XPATH)
+        labels << label_node.text unless label_node.empty?
+      end
+
+      labels
+    end
+  end
+  # class LaunchAgentManager
+
+  # rubocop: disable Metrics/MethodLength
+  def main(args = Watcher::ArgumentsParser.parse)
+    log.log_level = args[:log_level]
+    manager = Watcher::LaunchAgentManager.new(args)
+    if args[:show_all]
+      manager.show_all_launch_agents
+    elsif args[:list]
+      manager.list_launch_agent_labels
+    elsif args[:remove]
+      manager.remove_launch_agent(args[:remove])
+    else
+      manager.create_launch_agent(
+        args[:executable_path_with_args],
+        args[:watch_path].first,
+        *args[:watch_path]
+      )
+    end
+  end
+  # rubocop: enable Metrics/MethodLength
+end
+# module Watcher
+
+Object.new.extend(Watcher).main if $PROGRAM_NAME == __FILE__

data/lib/kanseishitsu/which.rb

@@ -0,0 +1,38 @@
+# encoding: utf-8
+# frozen_string_literal: false
+
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+# Copyright Nels Nelson 2024 but freely usable (see license)
+
+# Define module Which
+module Which
+  # Find the full path to a given executable in the PATH
+  # system environment variable
+  def find_executable_in_path(cmd)
+    return if cmd.nil?
+
+    directory = ENV['PATH'].split(File::PATH_SEPARATOR).find do |dir|
+      File.executable?(File.join(dir, cmd))
+    end
+    directory.nil? ? nil : File.join(directory, cmd)
+  end
+
+  def executable?(exe)
+    !exe.empty? && File.executable?(exe) && !File.directory?(exe)
+  end
+
+  def explicit_which(cmd)
+    exe = `which #{cmd}`.chomp
+    executable?(exe) ? exe : nil
+  rescue Errno::ENOENT => _e
+    nil
+  end
+
+  def portable_which(cmd)
+    explicit_which(cmd) || find_executable_in_path(cmd)
+  end
+  alias which portable_which
+end
+# module Which