karules 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 276d1cb288bdf01c66130cebd08d2ffb2723f7e2b8fce6cbe6ffa97a0aa430d5
-  data.tar.gz: 5dd19e077072c671737e8fef8093e1f05b97a871a38c850bb24cfb0859e80935
+  metadata.gz: f8598b4746e38d1ede0dfeef75a5c4eddaf8807f4684db40c8caf9a4361d6a07
+  data.tar.gz: 8ad72a2d0032d080df898bff9041afcdd4546beed36f69f10fd0092d524dada6
 SHA512:
-  metadata.gz: 9933c4488162a5fd9e792c3dce4e220982d3a1709d6c9c511e123d8d0a798ba9a7c10c9925750fca3c4a1a5def0568c1a646b535d79f6f312a4530b02b76acfc
-  data.tar.gz: 2fc49300015041c4ea3dd9ade8b6dbbb0823669316013a7af98f14ffeefbeef0d733ea41ea3eb896ab4afcff103940076dddb259a046e4f8d2616c0e6ce4495e
+  metadata.gz: 543bf369b4c3001e2a8f87c31f5e7e5fe36dfad40101a0736dc1d48e764845390f43ea137358d18206b58e742a457caadef580004d92827345e8af73c18baea2
+  data.tar.gz: a4b1004847086e33a791f5c77a9d1af88159ed5ad5c76d3fdd26ced1fb028c14a10dc065cda12cdf68aa2c4b6b73c52ce24a7836b96654daa512a98daf64df20

data/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2025-01-23
+
+### Added
+- `--version` / `-v` flag to show gem version
+- `--help` / `-h` flag to show usage information
+- `init` command to generate sample config file
+- `--validate` / `--check` flag to validate config syntax without applying
+- `--dry-run` flag to preview changes without writing to Karabiner
+- `--verbose` flag for detailed output
+- `--no-backup` flag to skip automatic config backup
+- Automatic config file detection in multiple locations:
+  - `$XDG_CONFIG_HOME/karules/config.rb`
+  - `~/.config/karules/config.rb`
+  - `~/.karules.rb`
+  - `./karules.rb`
+- Automatic backup of existing Karabiner config before changes
+- Success message after config update showing file path
+- Better error messages and help text
+
+### Changed
+- CLI now uses OptionParser for robust argument handling
+- Config file path is now optional (auto-detected)
+- Improved error messages when config file not found
+
 ## [0.1.0] - 2025-01-23
 
 ### Added
@@ -28,4 +52,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Group organization with descriptions
 - Deep hash sorting for consistent JSON output
 
-[0.1.0]: https://github.com/avsej/karules/releases/tag/v0.1.0
+[0.2.0]: https://github.com/dzirtusss/karules/releases/tag/v0.2.0
+[0.1.0]: https://github.com/dzirtusss/karules/releases/tag/v0.1.0

data/README.md

@@ -44,7 +44,7 @@ Much better.
 
 ## Installation
 
-### Via Homebrew (soon)
+### Via Homebrew (recommended)
 
 ```bash
 brew tap dzirtusss/tap
@@ -57,15 +57,6 @@ brew install karules
 gem install karules
 ```
 
-### Manual
-
-```bash
-git clone https://github.com/dzirtusss/karules.git
-cd karules
-gem build karules.gemspec
-gem install karules-0.1.0.gem
-```
-
 ## Configuration
 
 Create your config file at `~/.config/karules/config.rb`:
@@ -122,6 +113,74 @@ karules
 
 It will update your `~/.config/karabiner/karabiner.json` automatically.
 
+## CLI Commands
+
+### Generate a config file
+
+```bash
+karules init
+```
+
+Creates `~/.config/karules/config.rb` with examples. Edit this file to add your mappings.
+
+### Apply your config
+
+```bash
+karules                    # Auto-detect config file
+karules my-config.rb       # Use specific file
+```
+
+### Validate config
+
+```bash
+karules --validate         # Check syntax without applying
+```
+
+### Preview changes
+
+```bash
+karules --dry-run          # See what would change
+```
+
+### Show version
+
+```bash
+karules --version
+```
+
+### Get help
+
+```bash
+karules --help
+```
+
+### All options
+
+```
+Usage: karules [COMMAND|CONFIG_FILE] [OPTIONS]
+
+Commands:
+  init              Generate a sample config file
+  run [FILE]        Load and apply config (default)
+
+Options:
+  -v, --version     Show version
+  -h, --help        Show this help
+  --verbose         Show detailed output
+  --dry-run         Preview changes without applying
+  --validate        Validate config syntax only
+  --no-backup       Skip backup of existing config
+```
+
+### Config file auto-detection
+
+karules automatically searches for config files in this order:
+1. Explicit path argument
+2. `$XDG_CONFIG_HOME/karules/config.rb`
+3. `~/.config/karules/config.rb`
+4. `~/.karules.rb`
+5. `./karules.rb`
+
 ## Usage
 
 ### Basic Mapping

data/examples/config.rb

@@ -40,14 +40,7 @@ class MyKaRules < KaRules
       app_unless(:ghostty) do
         # Example: Focus terminal app, wait, then send Ctrl+A
         # Replace with your own terminal focus script
-        m(
-          "a +control",
-          [
-            "!open -a 'Terminal'",
-            { key_code: "vk_none", hold_down_milliseconds: 100 },
-            "a +control"
-          ]
-        )
+        m("a +control", ["!open -a 'Terminal'", { key_code: "vk_none", hold_down_milliseconds: 100 }, "a +control"])
       end
     end
 

data/exe/karules

@@ -1,30 +1,278 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+require "English"
+require "fileutils"
 require "karules"
+require "optparse"
 
-# Determine config file path
-config_file = ARGV.first
+# CLI handler for karules
+class KarulesCLI
+  attr_reader :options
 
-unless config_file
-  # Use XDG_CONFIG_HOME or default to ~/.config
-  config_home = ENV.fetch("XDG_CONFIG_HOME", File.expand_path("~/.config"))
-  config_file = File.join(config_home, "karules", "config.rb")
-end
+  BASIC_CONFIG_TEMPLATE = <<~RUBY
+    # frozen_string_literal: true
+
+    require "karules"
+
+    class MyKaRules < KaRules
+      def config
+        # Define your application bundle identifiers
+        apps(
+          terminal: "^com\\\\.apple\\\\.Terminal$",
+          safari: "^com\\\\.apple\\\\.Safari$"
+        )
+
+        # Simple mapping example
+        group("Caps Lock to Control") do
+          m("caps_lock -any", "left_control")
+        end
+
+        # App launcher example
+        group("Quick App Launcher") do
+          m("t +right_command", "!open -a 'Terminal'")
+          m("s +right_command", "!open -a 'Safari'")
+        end
+
+        # Modal mode example (vim-style navigation)
+        group("Tab Navigation Mode") do
+          m("tab", "right_option lazy", to_if_alone: "tab")
+          m("h +right_option", "left_arrow")
+          m("j +right_option", "down_arrow")
+          m("k +right_option", "up_arrow")
+          m("l +right_option", "right_arrow")
+        end
+
+        # Add more groups and mappings here
+      end
+    end
+
+    MyKaRules.new.call
+  RUBY
+  private_constant :BASIC_CONFIG_TEMPLATE
+
+  def initialize
+    @options = { verbose: false, dry_run: false, validate: false, backup: true }
+  end
+
+  def run(args)
+    parse_options(args)
+
+    command = args.shift || "run"
+
+    case command
+    when "init"
+      init_config
+    when "run", nil
+      run_config(args.first)
+    when "version", "--version", "-v"
+      show_version
+    when "help", "--help", "-h"
+      show_help
+    else
+      run_config(command) # Treat as config file path
+    end
+  end
+
+  private
+
+  def parse_options(args)
+    parser =
+      OptionParser.new do |opts|
+        opts.banner = "Usage: karules [COMMAND|CONFIG_FILE] [OPTIONS]"
+        opts.separator("")
+        opts.separator("Commands:")
+        opts.separator("  init           Generate a sample config file")
+        opts.separator("  run [FILE]     Load and apply config (default command)")
+        opts.separator("")
+        opts.separator("Options:")
+
+        opts.on("-v", "--version", "Show version") do
+          show_version
+          exit(0)
+        end
+
+        opts.on("-h", "--help", "Show this help") do
+          puts(opts)
+          exit(0)
+        end
+
+        opts.on("--verbose", "Show detailed output") do
+          @options[:verbose] = true
+        end
+
+        opts.on("--dry-run", "Preview changes without applying") do
+          @options[:dry_run] = true
+        end
+
+        opts.on("--validate", "--check", "Validate config syntax without applying") do
+          @options[:validate] = true
+        end
+
+        opts.on("--no-backup", "Skip backup of existing Karabiner config") do
+          @options[:backup] = false
+        end
+      end
+    parser.parse!(args)
+  end
+
+  def show_version
+    puts("karules #{Karules::VERSION}")
+  end
+
+  def show_help
+    puts(<<~HELP)
+      karules - Configure Karabiner-Elements with Ruby DSL
+
+      Usage:
+        karules [COMMAND|CONFIG_FILE] [OPTIONS]
+
+      Commands:
+        init              Generate a sample config file
+        run [FILE]        Load and apply config (default)
+
+      Options:
+        -v, --version     Show version
+        -h, --help        Show this help
+        --verbose         Show detailed output
+        --dry-run         Preview changes without applying
+        --validate        Validate config syntax only
+        --no-backup       Skip backup of existing config
+
+      Examples:
+        karules                           # Use default config
+        karules init                      # Generate sample config
+        karules my-config.rb              # Use specific config
+        karules --dry-run                 # Preview changes
+        karules --validate                # Check syntax only
+
+      Config file locations (searched in order):
+        1. Explicit path argument
+        2. $XDG_CONFIG_HOME/karules/config.rb
+        3. ~/.config/karules/config.rb
+        4. ~/.karules.rb
+        5. ./karules.rb
+    HELP
+  end
+
+  def init_config
+    config_dir = File.join(ENV.fetch("XDG_CONFIG_HOME", File.expand_path("~/.config")), "karules")
+    config_file = File.join(config_dir, "config.rb")
+
+    if File.exist?(config_file) # rubocop:disable Style/MissingElse
+      warn("Config file already exists: #{config_file}")
+      warn("Remove it first or edit it manually.")
+      exit(1)
+    end
+
+    FileUtils.mkdir_p(config_dir)
+
+    # Get example config from gem
+    gem_root = File.expand_path("../..", __dir__)
+    example_file = File.join(gem_root, "examples", "config.rb")
+
+    if File.exist?(example_file)
+      FileUtils.cp(example_file, config_file)
+    else
+      # Fallback: create basic config
+      File.write(config_file, BASIC_CONFIG_TEMPLATE)
+    end
+
+    puts("✓ Created config file: #{config_file}")
+    puts("")
+    puts("Edit this file to customize your keyboard mappings.")
+    puts("Then run: karules")
+  end
+
+  def run_config(explicit_path)
+    config_file = find_config_file(explicit_path)
+
+    log("Using config: #{config_file}")
+
+    if @options[:validate] # rubocop:disable Style/MissingElse
+      validate_config(config_file)
+      puts("✓ Config syntax is valid")
+      exit(0)
+    end
+
+    # Set environment variables for DSL
+    ENV["KARULES_DRY_RUN"] = "1" if @options[:dry_run]
+    ENV["KARULES_BACKUP"] = @options[:backup] ? "1" : "0"
+    ENV["KARULES_VERBOSE"] = "1" if @options[:verbose]
+
+    # Load and execute the config
+    load(config_file)
+
+    if @options[:dry_run]
+      puts("")
+      puts("✓ Dry run complete - no changes were made")
+      puts("  Run without --dry-run to apply changes")
+    else
+      config_home = ENV.fetch("XDG_CONFIG_HOME", File.expand_path("~/.config"))
+      karabiner_file = File.join(config_home, "karabiner", "karabiner.json")
+      puts("")
+      puts("✓ Karabiner config updated successfully")
+      puts("  Config file: #{karabiner_file}")
+    end
+  end
+
+  def find_config_file(explicit_path)
+    if explicit_path # rubocop:disable Style/MissingElse
+      return explicit_path if File.exist?(explicit_path)
+
+      warn("Config file not found: #{explicit_path}")
+      exit(1)
+    end
+
+    # Auto-detect config file
+    candidates = [
+      File.join(ENV.fetch("XDG_CONFIG_HOME", File.expand_path("~/.config")), "karules", "config.rb"),
+      File.expand_path("~/.config/karules/config.rb"),
+      File.expand_path("~/.karules.rb"),
+      File.expand_path("./karules.rb")
+    ]
+
+    config_file = candidates.find { |f| File.exist?(f) }
+
+    unless config_file
+      warn("No config file found. Searched:")
+      candidates.each { |f| warn("  - #{f}") }
+      warn("")
+      warn("Create a config file with: karules init")
+      warn("Or specify a path: karules /path/to/config.rb")
+      exit(1)
+    end
+
+    config_file
+  end
+
+  def validate_config(config_file)
+    log("Validating config syntax...")
+
+    # Try to load the file and check for syntax errors
+    begin
+      # Use ruby -c to check syntax
+      output = `ruby -c "#{config_file}" 2>&1`
+      exit_code = $CHILD_STATUS.exitstatus
+
+      if exit_code != 0 # rubocop:disable Style/MissingElse
+        warn("Syntax error in config file:")
+        warn(output)
+        exit(1)
+      end
+
+      log("Syntax check passed")
+    rescue StandardError => e
+      warn("Error validating config: #{e.message}")
+      exit(1)
+    end
+  end
 
-# Check if config file exists
-unless File.exist?(config_file)
-  warn "Config file not found: #{config_file}"
-  warn ""
-  warn "Usage: karules [CONFIG_FILE]"
-  warn ""
-  warn "Create a config file at #{config_file}"
-  warn "or specify a custom path as an argument."
-  warn ""
-  warn "See the example config at:"
-  warn "  #{File.expand_path('../../examples/config.rb', __dir__)}"
-  exit 1
+  def log(message)
+    puts(message) if @options[:verbose]
+  end
 end
 
-# Load and execute the config file
-load config_file
+# Run the CLI
+cli = KarulesCLI.new
+cli.run(ARGV.dup)

data/lib/karules/dsl.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
-# rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+require "fileutils"
 # rubocop:disable Metrics/PerceivedComplexity,Metrics/CyclomaticComplexity
 
 require "json"
 
 module KaRulesDSL # rubocop:disable Metrics/ModuleLength
   APPLE_KEYS = %w[spotlight].freeze
+  private_constant :APPLE_KEYS
 
   def m(
     from, to = nil, conditions: nil, to_if_alone: nil, to_delayed_action: nil,
@@ -50,7 +51,7 @@ module KaRulesDSL # rubocop:disable Metrics/ModuleLength
         result[:modifiers][:optional] ||= []
         result[:modifiers][:optional] << mod[1..]
       else
-        raise("Unknown modifier: #{mod}")
+        raise(ArgumentError, "Unknown modifier: #{mod}")
       end
     end
     result
@@ -73,7 +74,7 @@ module KaRulesDSL # rubocop:disable Metrics/ModuleLength
       #   result[:shell_command] = mod[1..] + args.split(mod).last
       #   break
       else
-        raise("Unknown modifier: #{mod}")
+        raise(ArgumentError, "Unknown modifier: #{mod}")
       end
     end
     result
@@ -104,7 +105,7 @@ module KaRulesDSL # rubocop:disable Metrics/ModuleLength
     if block_given?
       conditions(app_if(name), &)
     else
-      app = @apps[name] || raise("Unknown app: #{name}")
+      app = @apps[name] || raise(ArgumentError, "Unknown app: #{name}")
       { bundle_identifiers: wrap(app), type: "frontmost_application_if" }
     end
   end
@@ -113,7 +114,7 @@ module KaRulesDSL # rubocop:disable Metrics/ModuleLength
     if block_given?
       conditions(app_unless(name), &)
     else
-      app = @apps[name] || raise("Unknown app: #{name}")
+      app = @apps[name] || raise(ArgumentError, "Unknown app: #{name}")
       { bundle_identifiers: wrap(app), type: "frontmost_application_unless" }
     end
   end
@@ -170,10 +171,20 @@ module KaRulesDSL # rubocop:disable Metrics/ModuleLength
   end
 
   def call
+    # Generate rules (this also loads the config which may set karabiner_path)
+    rules = generate
+
+    # Now we can determine the correct file path
     file = karabiner_path || default_karabiner_path
+
+    # Backup existing file if requested (unless in dry-run mode)
+    backup_file(file) if should_backup? && !dry_run?
+
     json = JSON.parse(File.read(file), symbolize_names: true)
 
-    json[:profiles][0][:complex_modifications][:rules].replace(generate)
+    json[:profiles][0][:complex_modifications][:rules].replace(rules)
+
+    return if dry_run? # Don't write in dry-run mode
 
     File.write(file, json.to_json)
     `karabiner_cli --format-json #{file}`
@@ -181,6 +192,22 @@ module KaRulesDSL # rubocop:disable Metrics/ModuleLength
 
   private
 
+  def dry_run?
+    ENV["KARULES_DRY_RUN"] == "1"
+  end
+
+  def should_backup?
+    ENV["KARULES_BACKUP"] != "0"
+  end
+
+  def backup_file(file)
+    return unless File.exist?(file)
+
+    backup_path = "#{file}.backup.#{Time.now.strftime('%Y%m%d_%H%M%S')}"
+    FileUtils.cp(file, backup_path)
+    puts("Backed up existing config to: #{backup_path}") if ENV["KARULES_VERBOSE"] == "1"
+  end
+
   def default_karabiner_path
     config_home = ENV.fetch("XDG_CONFIG_HOME", File.expand_path("~/.config"))
     File.join(config_home, "karabiner", "karabiner.json")
@@ -191,7 +218,8 @@ module KaRulesDSL # rubocop:disable Metrics/ModuleLength
     when Array
       obj.map { |el| deep_sort(el) }
     when Hash
-      obj.sort_by { |k, _| k }.to_h.transform_values { |v| deep_sort(v) }
+      obj.sort_by { |k, _| k }
+         .to_h.transform_values { |v| deep_sort(v) }
     else
       obj
     end

data/lib/karules/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Karules
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
+  public_constant :VERSION
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: karules
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Sergey Tarasov
@@ -10,6 +10,34 @@ bindir: exe
 cert_chain: []
 date: 2025-11-23 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement