kanseishitsu 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 25050a62712f4707b8f1b388647b618d7d722fc15f9a7713a6a2b06d504236d6
+  data.tar.gz: adf5c5eba9308caeb08cec65eefa966caf9f9ab6784eeef243d50030be5a0f79
+SHA512:
+  metadata.gz: 1ec5b00e46746dbf649876030ca6b7825471c2e4d22ea1f8ba5af2ca7adbdc03328ae61be34b74f81537c99aa4cc75be9dcd60425f44a60584ec433121c6f8a2
+  data.tar.gz: 6f89365ab7c0d2cc4d724ec71fae360cc66d70bb94492b209b66dba2cb23f470d22fcb634b7eb1776190774c8aa36ea0131304c9060c35a7e569a69a54f80eda

data/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Nels Nelson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,141 @@
+# kanseishitsu
+
+A user who wishes to define their own cron jobs and file monitors in macOS faces some obstacles.
+
+As of 2024, the current state of the art relies on XML plist files to define jobs in the `Library/LaunchAgents` directory in a user's home directory.
+
+XML is not a very simple format for a human being to read or write.
+
+If you already have the skills to read and write macOS LaunchAgent XML documents with ease, then the authors commend you for your determination and studiousness.
+
+Otherwise, for all of you lazy and ignorant people like the authors, this gem is for you!
+
+The `kanseishitsu` gem provides some little ruby scripts which will support simpler management of such launch agents.
+
+
+## Usage
+
+Here is some usage and examples for each script.
+
+
+### cron.rb
+
+The usage for `cron.rb`.
+
+The `cron.rb` executable uses something similar to a  `crontab` entry in GNU/Linux.
+
+```sh
+$ cron.rb --help
+Usage: cron.rb <crontab>|<options>
+
+Options:
+        --show-all                   Show all cron jobs
+    -l, --list                       List launch agent labels
+    -r, --remove=<label>             Remove a cron job by label
+```
+
+
+#### Example
+
+For example:
+
+```sh
+cron.rb "0 1 * * * archive.rb ~/Downloads/archive"
+```
+
+
+### watch.rb
+
+The usage for `watch.rb`.
+
+```sh
+$ watch.rb --help
+Usage: watch.rb <watch_path> <handler_program_path>
+
+Options:
+        --show-all                   Show watchers
+    -l, --list                       List launch agent labels
+    -r, --remove=<label>             Remove a watcher by label
+```
+
+
+#### Example
+
+For example:
+
+```sh
+watch.rb ~/Desktop ~/.local/usr/bin/desktop.rb
+```
+
+
+## Docker
+
+Build the docker image to support CI/CD containers.
+
+```sh
+docker buildx build --tag="$(basename $(pwd))" .
+docker run --interactive --tty --rm --name "$(basename $(pwd))" "$(basename $(pwd))"
+```
+
+
+## Name meaning that nobody should really care about
+
+The Japanese word "管制室" (Kanseishitsu) translates to "control room" in English. It refers to a room from which operations are directed or monitored, typically involving equipment and personnel to oversee and manage various functions such as in factories, airports, or television studios.
+
+Pronounced: Kahn-say-she-tsu
+
+Here's how to say each part:
+
+- Kahn: like the beginning of "con" in "convenient," but with a more open 'a' sound.
+- Say: just like the English word "say."
+- She: as in "she."
+- Tsu: this part can be a bit tricky because it's not a sound typically found in English. It's similar to saying "sue," but start it with a soft 't' sound placed right before the 's'.
+
+
+## Project file tree
+
+Here is a bird's-eye view of the project layout.
+
+```sh
+date && tree -A -I "Gemfile.lock|*.gem|tmp|vendor"
+Wed May 15 23:07:43 CDT 2024
+.
+├── Dockerfile
+├── Gemfile
+├── LICENSE.md
+├── README.md
+├── Rakefile
+├── bin
+│   ├── cron.rb
+│   └── watch.rb
+├── kanseishitsu.gemspec
+├── kanseishitsu.png
+├── lib
+│   ├── kanseishitsu
+│   │   ├── cron
+│   │   │   ├── argument_parser.rb
+│   │   │   └── launch_agent_manager_rexml.rb
+│   │   ├── cron.rb
+│   │   ├── launch_agent_constants.rb
+│   │   ├── launch_agent_manager.rb
+│   │   ├── logging.rb
+│   │   ├── plist_parser.rb
+│   │   ├── version.rb
+│   │   ├── watch
+│   │   │   └── argument_parser.rb
+│   │   ├── watch.rb
+│   │   ├── which.rb
+│   │   ├── xml_helper.rb
+│   │   └── xml_helper_rexml.rb
+│   └── kanseishitsu.rb
+├── scripts
+│   └── version_bump.sh
+└── spec
+    ├── spec_helper.rb
+    ├── test_spec.rb
+    └── verify
+        ├── launchctl.rb
+        └── verify_spec.rb
+
+8 directories, 28 files
+```

data/bin/cron.rb

@@ -0,0 +1,27 @@
+#! /usr/bin/env ruby
+
+# encoding: utf-8
+# frozen_string_literal: false
+
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+# Copyright Nels Nelson 2024 but freely usable (see license)
+
+# Usage: cron.rb <crontab>|<options>
+#
+# Options:
+#         --show-all                   Show cron jobs
+#     -l, --list                       List cron jobs labels
+#     -r, --remove=<label>             Remove a cron job by label
+#
+# Examples:
+#
+# cron.rb "0 1 * * * archive.rb ${HOME}/Downloads/archive"
+# cron.rb --show-all
+# cron.rb --list
+# cron.rb --remove=com.local.archive
+
+require_relative '../lib/kanseishitsu'
+
+Object.new.extend(Cron).main

data/bin/watch.rb

@@ -0,0 +1,27 @@
+#! /usr/bin/env ruby
+
+# encoding: utf-8
+# frozen_string_literal: false
+
+# -*- mode: ruby -*-
+# vi: set ft=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 '../lib/kanseishitsu'
+
+Object.new.extend(Watcher).main

data/lib/kanseishitsu/cron/argument_parser.rb

@@ -0,0 +1,120 @@
+# encoding: utf-8
+# frozen_string_literal: false
+
+# vi: set ft=ruby :
+# -*- mode: ruby -*-
+
+# Copyright Nels Nelson 2024 but freely usable (see license)
+
+require 'logger'
+require 'optparse'
+
+require_relative '../version'
+
+# Define module Cron
+module Cron
+  # Define the ArgumentsParser class
+  class ArgumentsParser
+    FLAGS = %i[banner show_all list remove verbose version].freeze
+    POSITIONAL = %i[crontab].freeze
+    attr_reader :parser, :options
+
+    def initialize(option_parser = OptionParser.new)
+      @parser = option_parser
+      @options = {}
+      FLAGS.each { |method_name| self.method(method_name).call }
+    end
+
+    def banner
+      @parser.banner = "Usage: #{File.basename($PROGRAM_NAME)} <crontab>|<options>"
+      @parser.separator ''
+      @parser.separator 'Options:'
+    end
+
+    def show_all
+      @parser.on('--show-all', 'Show cron jobs') do
+        @options[:show_all] = true
+      end
+    end
+
+    def list
+      @parser.on('-l', '--list', 'List cron jobs labels') do
+        @options[:list] = true
+      end
+    end
+
+    def remove
+      @parser.on('-r', '--remove=<label>', 'Remove a cron job 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 crontab(args)
+      crontab = args.shift.gsub(/\A['"]|['"]\z/, '').split
+      @options[:crontab] = crontab
+      @options[:cron_schedule] =
+        crontab.take(LaunchAgentManager::SCHEDULE_PARTS_COUNT).join(' ')
+      @options[:executable_path_with_args] =
+        crontab.drop(LaunchAgentManager::SCHEDULE_PARTS_COUNT).join(' ')
+    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 != 1
+        message = 'A crontab definition 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 Cron

data/lib/kanseishitsu/cron/launch_agent_manager_rexml.rb

@@ -0,0 +1,183 @@
+# encoding: utf-8
+# frozen_string_literal: false
+
+# vi: set ft=ruby :
+# -*- mode: ruby -*-
+
+# Copyright Nels Nelson 2024 but freely usable (see license)
+
+require 'rexml/formatters/pretty'
+
+require 'fileutils'
+
+require_relative '../launch_agent_plist'
+
+# Define module LaunchAgentManagerConstants
+module LaunchAgentManagerConstants
+  VERSION = '0.1.0'.freeze unless defined?(VERSION)
+  LABEL_NAMESPACE = %w[com local].freeze
+  INTERVALS = %w[Minute Hour Day Month Weekday].freeze
+  SCHEDULE_PARTS_COUNT = INTERVALS.length
+  LAUNCHCTL_TEMPLATE = 'launchctl bootstrap gui/%<uid>s %<plist>s'.freeze
+  SUCCESS_MESSAGE = 'Created and enabled launchd job: %<label>s'.freeze
+  LAUNCH_AGENTS_DIR_PATH = File.expand_path(File.join(Dir.home, 'Library', 'LaunchAgents'))
+  BOOTOUT_TEMPLATE = 'launchctl bootout gui/%<uid>s/%<label>s'.freeze
+  REMOVE_TEMPLATE = 'launchctl remove gui/%<uid>s/%<label>s'.freeze
+end
+
+# Define module LaunchAgentManagerInstanceMethods
+module LaunchAgentManagerInstanceMethods
+  include LaunchAgentManagerConstants
+
+  def find_executable_in_path(cmd)
+    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
+
+  # Extract program path and arguments, verifying executable
+  # rubocop: disable Metrics/MethodLength
+  def extract_program_path(executable_with_args)
+    *args = executable_with_args.split
+    exe = args.shift
+    exe_path = File.exist?(exe) ? exe : portable_which(exe)
+    if exe_path.nil? || !File.exist?(exe_path)
+      abort "Cannot find executable in path: #{exe}"
+    end
+    if exe_path.nil? || !File.executable?(exe_path) || File.directory?(exe_path)
+      abort "Given file is not executable: #{exe}"
+    end
+    args.unshift(exe_path)
+    args
+  end
+  # rubocop: enable Metrics/MethodLength
+
+  # Create the job name based on the given executable file path
+  def derive_job_label_from_executable(exe_path)
+    label = LABEL_NAMESPACE.dup
+    label << File.basename(exe_path, '.*')
+    label.join('.')
+  end
+
+  # Define cron settings for plist
+  def derive_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
+
+  # Save plist file to LaunchAgents directory; do not overwrite an
+  # already existing file with the same name at the generated path
+  # rubocop: disable Metrics/MethodLength
+  def save_plist(label, doc)
+    FileUtils.mkdir_p(LAUNCH_AGENTS_DIR_PATH)
+    plist_path = File.join(LAUNCH_AGENTS_DIR_PATH, "#{label}.plist")
+    puts "plist_path: #{plist_path}"
+    return plist_path if File.exist?(plist_path)
+
+    document = ''
+    formatter = REXML::Formatters::Pretty.new(4)
+    formatter.write(doc, document)
+    puts '[DEBUG] Contents of plist xml document:'
+    puts document
+    File.write(plist_path, document)
+    plist_path
+  end
+  # rubocop: enable Metrics/MethodLength
+
+  def execute(command)
+    puts "[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
+
+  # Show the launchd agents as crontabs
+  def show_all_cron_jobs
+    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
+
+  # Return a list of all user launchd agent labels
+  def launch_agent_labels
+    plist_file_paths = Dir.glob(File.join(LAUNCH_AGENTS_DIR_PATH, '*.plist'))
+    plist_file_paths.each_with_object([]) do |file_path, labels|
+      label = LaunchAgentPlist.parse(file_path)[:label]
+      labels << label unless label.nil?
+    end
+  end
+
+  # List labels of launchd agents
+  def list_launch_agent_labels
+    launch_agent_labels.each do |label|
+      puts label
+    end
+  end
+
+  # Remove plist Launch Agents by label
+  def remove_cron_job(label)
+    # warn "[DEBUG] Removing launch agent: #{label}"
+    plist_path = File.expand_path(File.join(LAUNCH_AGENTS_DIR_PATH, "#{label}.plist"))
+    # warn "[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
+
+  # Create the launchd job
+  def create_launchd_job(options)
+    args = extract_program_path(options[:executable_path_with_args])
+    label = derive_job_label_from_executable(args.first)
+    calendar_interval = derive_calendar_interval(options[:cron_schedule])
+    plist_doc = LaunchAgentPlist.new(label, args, calendar_interval).to_doc
+    plist_path = save_plist(label, plist_doc)
+    puts "Executing: cat #{plist_path}"
+    puts `cat #{plist_path}`.strip
+    load_launchd_job(plist_path)
+    puts format(SUCCESS_MESSAGE, label: label)
+  end
+end
+# module LaunchAgentManagerInstanceMethods
+
+# Define the LaunchAgentManager class
+class LaunchAgentManager
+  include LaunchAgentManagerInstanceMethods
+
+  attr_reader :options
+
+  def initialize(options)
+    @options = options
+  end
+end

data/lib/kanseishitsu/cron.rb

@@ -0,0 +1,53 @@
+#! /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: cron.rb <crontab>|<options>
+#
+# Options:
+#         --show-all                   Show cron jobs
+#     -l, --list                       List cron jobs labels
+#     -r, --remove=<label>             Remove a cron job by label
+#
+# Examples:
+#
+# cron.rb "0 1 * * * archive.rb ${HOME}/Downloads/archive"
+# cron.rb --show-all
+# cron.rb --list
+# cron.rb --remove=com.local.archive
+
+require_relative 'launch_agent_manager'
+require_relative 'cron/argument_parser'
+
+# Define module Cron
+module Cron
+  LaunchAgentManager = ::LaunchAgentManager
+
+  # rubocop: disable Metrics/MethodLength
+  def main(args = Cron::ArgumentsParser.parse)
+    log.log_level = args[:log_level]
+    manager = Cron::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],
+        nil,
+        args[:cron_schedule]
+      )
+    end
+  end
+  # rubocop: enable Metrics/MethodLength
+end
+# module Cron
+
+Object.new.extend(Cron).main if $PROGRAM_NAME == __FILE__

data/lib/kanseishitsu/launch_agent_constants.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+# frozen_string_literal: false
+
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+# Copyright Nels Nelson 2024 but freely usable (see license)
+
+# Define the LaunchAgentConstants module
+module LaunchAgentConstants
+  DEFAULT_ENCODING = 'UTF-8'.freeze
+  DOCTYPE_ELEMENT = '<!%<doctypes>s>'.freeze
+  DOCTYPES = [
+    'DOCTYPE',
+    'plist',
+    'PUBLIC',
+    '"-//Apple//DTD PLIST 1.0//EN"',
+    '"http://www.apple.com/DTDs/PropertyList-1.0.dtd"'
+  ].freeze
+  LABEL_NAMESPACE = %w[com local].freeze
+  INTERVALS = %w[Minute Hour Day Month Weekday].freeze
+  SCHEDULE_PARTS_COUNT = INTERVALS.length
+  CDATA_PATTERN = %r{[<>&'"\n]+}
+  SCHEDULE_XPATH_TEMPLATE = './/key[text()="%<key>s"]/following-sibling::integer'.freeze
+  KEYS_REQUIRING_CDATA = ['PATH'].freeze
+  LAUNCHCTL_TEMPLATE = 'launchctl bootstrap gui/%<uid>s %<plist>s'.freeze
+  SUCCESS_MESSAGE = 'Created and enabled launchd job: %<label>s'.freeze
+  LAUNCH_AGENTS_DIR_PATH = File.expand_path(File.join(Dir.home, 'Library', 'LaunchAgents'))
+  LABEL_XPATH = '//key[text()="Label"]/following-sibling::*[1]'.freeze
+  START_CALENDAR_INTERVAL_XPATH =
+    '//key[text()="StartCalendarInterval"]/following-sibling::*[1]'.freeze
+  WATCH_PATHS_XPATH = '//key[text()="WatchPaths"]/following-sibling::*[1]'.freeze
+  LOCAL_STRING_XPATH = './string'.freeze
+  PROGRAM_ARGUMENTS_XPATH =
+    '//key[text()="ProgramArguments"]/following-sibling::array[1]'.freeze
+  INTERVAL_XPATH_TEMPLATE = './key[text()="%<key>s"]/following-sibling::*[1]'.freeze
+  BOOTOUT_TEMPLATE = 'launchctl bootout gui/%<uid>s/%<label>s'.freeze
+  REMOVE_TEMPLATE = 'launchctl remove gui/%<uid>s/%<label>s'.freeze
+  ON_LOGIN = '@login'.freeze
+end
+# module LaunchAgentConstants