dotsync 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0da622d8ef82d600401b7464c4ad28be7872fa942c252d00273378bcbdab2788
-  data.tar.gz: db97edbc75bb40ddd8353d97d2b3d255da9caa298dde368a58963e1f000bbc2d
+  metadata.gz: c060e4f84252048c1b038e350efcf900bc5b62b6bab5285dc9b1a2a9d0d0da0f
+  data.tar.gz: 5bef34fde923690c3ffaf68b3d5ed77d2195006d91d8b4f2c59853533c285339
 SHA512:
-  metadata.gz: f1f7fd2a2bb4d39df4c8a4286fb4ce750b55f5e3d4b0fb1a1bfa6a7902f5e6106919bb4dd1981057c583931fd4bf6534c64dc8161175caf38159bcb9dd5f93d5
-  data.tar.gz: a79078d32865500b76f5a27959bc426523a73ea31ec966aee7085b4786e024f9b7716dce1cb014323848228c64706618b91a9dfcd1a8ff5913817f165996c426
+  metadata.gz: 7049966bedd67e25b008ad9a7bae1697f54d189dc7f666bd42495a242af68b8c9494ead4c3e5310e500ce516db47270d5ae0f0382035b50df5d09543a631192f
+  data.tar.gz: 7abedab0ed8d49946e5b832ad38390968f17c6a7e32da3a3d774a47117767f1eec9dc3cbefd20a2f815eed5b091dcab73c4e9612b21d67fb1b7f85a0b8499ed1

data/CHANGELOG.md

@@ -1,3 +1,34 @@
+## [0.2.3] - 2026-02-08
+
+**New Features:**
+- Add per-mapping post-sync hooks that run commands after files are transferred
+  - `post_sync` — runs after sync in both directions (`[[sync]]` mappings)
+  - `post_push` — runs only after push (`[[sync]]` and `[[push]]` mappings)
+  - `post_pull` — runs only after pull (`[[sync]]` and `[[pull]]` mappings)
+  - Template variables: `{files}` (shell-quoted changed dest paths), `{src}`, `{dest}`
+  - Hooks only execute when files actually changed and only with `--apply`
+  - Hook failures log errors but do not abort remaining hooks or mappings
+  - Preview mode shows what commands would run without executing
+- Add `HookError` error class for hook-related errors
+- Add hook icon (󰜎) to mappings legend with custom icon support
+
+**New Files:**
+- `lib/dotsync/utils/hook_runner.rb` — HookRunner utility with execute, preview, and template expansion
+- `spec/dotsync/utils/hook_runner_spec.rb` — Comprehensive tests for HookRunner
+
+**Documentation:**
+- Add "Post-Sync Hooks" section to README with hook types, examples, template variables, and real-world use cases
+- Add post-sync hooks to Key Features and Table of Contents
+
+**Testing:**
+- Add 35 new test examples covering hooks across all layers
+  - HookRunner: template expansion, multiple commands, failure handling, shell-escaped paths, preview mode
+  - Mapping: hooks attribute, has_hooks?, hook icon display
+  - SyncMappings: direction resolution, array concatenation, shorthand hooks, validation of invalid keys
+  - PushActionConfig/PullActionConfig: hook extraction, validation of unidirectional constraints
+  - PushAction/PullAction: hook execution with changes, skipped without changes, skipped in dry-run
+- Total: 467 examples, 0 failures | Line: 96.45% | Branch: 82.86%
+
 ## [0.2.2] - 2025-02-07
 
 **New Features:**
@@ -17,7 +48,6 @@
 - Add integration tests for glob patterns in FileTransfer (including force mode)
 - Add integration tests for glob patterns in DirectoryDiffer
 - All 432 tests pass with 96.29% line coverage
-
 ## [0.2.1] - 2025-02-06
 
 **Performance Optimizations:**

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    dotsync (0.2.2)
+    dotsync (0.2.3)
       fileutils (~> 1.7.3)
       find (~> 0.2.0)
       listen (~> 3.9.0)

data/README.md

@@ -19,6 +19,7 @@ Dotsync is a powerful Ruby gem for managing and synchronizing your dotfiles acro
 - **Smart Filtering**: Use `force`, `only`, and `ignore` options to precisely control what gets synced
 - **Automatic Backups**: Pull operations create timestamped backups for easy recovery
 - **Live Watching**: Continuously monitor and sync changes in real-time with `watch` command
+- **Post-Sync Hooks**: Run commands automatically after files change (e.g., codesigning, chmod, service reload)
 - **Customizable Output**: Control verbosity and customize icons to match your preferences
 - **Auto-Updates**: Get notified when new versions are available
 
@@ -33,6 +34,7 @@ Dotsync is a powerful Ruby gem for managing and synchronizing your dotfiles acro
     - [Bidirectional Sync Mappings (Recommended)](#bidirectional-sync-mappings-recommended)
     - [Alternative: Unidirectional Mappings](#alternative-unidirectional-mappings)
     - [Mapping Options (force, only, ignore)](#force-only-and-ignore-options-in-mappings)
+    - [Post-Sync Hooks](#post-sync-hooks)
   - [Safety Features](#safety-features)
   - [Customizing Icons](#customizing-icons)
   - [Automatic Update Checks](#automatic-update-checks)
@@ -499,6 +501,84 @@ This configuration:
 
 These options apply when the source is a directory and are relevant for both `push` and `pull` operations.
 
+#### Post-Sync Hooks
+
+Hooks let you run commands automatically after a mapping's files are transferred. Hooks only execute when files actually changed, and only when using `--apply`.
+
+##### Hook Types
+
+| Hook | Description | Valid in |
+|------|-------------|----------|
+| `post_sync` | Runs after sync in both directions | `[[sync]]` mappings |
+| `post_push` | Runs only after push | `[[sync]]` and `[[push]]` mappings |
+| `post_pull` | Runs only after pull | `[[sync]]` and `[[pull]]` mappings |
+
+For sync mappings, hooks are resolved by direction:
+- **Push**: `post_sync` + `post_push` commands
+- **Pull**: `post_sync` + `post_pull` commands
+
+##### Examples
+
+**Single command (shorthand mapping):**
+```toml
+[[sync.xdg_bin]]
+force = true
+
+[sync.xdg_bin.hooks]
+post_sync = "codesign -s - {files}"
+```
+
+**Multiple commands (explicit sync):**
+```toml
+[[sync.mappings]]
+local  = "$XDG_CONFIG_HOME/scripts"
+remote = "$XDG_CONFIG_HOME_MIRROR/scripts"
+
+[sync.mappings.hooks]
+post_sync = ["codesign -s - {files}", "chmod 700 {files}"]
+post_pull = "launchctl kickstart -k gui/$(id -u)/com.example.service"
+```
+
+**Unidirectional mapping:**
+```toml
+[[pull.mappings]]
+src = "$DOTFILES_DIR/scripts"
+dest = "$HOME/Scripts"
+
+[pull.mappings.hooks]
+post_pull = ["codesign -s - {files}", "chmod 700 {files}"]
+```
+
+##### Template Variables
+
+| Variable | Description |
+|----------|-------------|
+| `{files}` | Shell-quoted paths of changed destination files |
+| `{src}` | The mapping's source path |
+| `{dest}` | The mapping's destination path |
+
+##### Real-World Examples
+
+```toml
+# Codesign scripts after pulling (macOS Ventura+ requirement for LaunchAgents)
+[[sync.xdg_bin]]
+force = true
+
+[sync.xdg_bin.hooks]
+post_pull = "codesign -s - {files}"
+
+# Reload a LaunchAgent after pulling config changes
+[[pull.mappings]]
+src = "$DOTFILES_DIR/LaunchAgents/com.example.plist"
+dest = "$HOME/Library/LaunchAgents/com.example.plist"
+
+[pull.mappings.hooks]
+post_pull = "launchctl kickstart -k gui/$(id -u)/com.example"
+```
+
+> [!NOTE]
+> In preview mode (without `--apply`), hooks are displayed as a preview showing what commands would run. Hook failures log errors but do not abort remaining hooks or mappings.
+
 ### Safety Features
 
 Dotsync includes several safety mechanisms to prevent accidental data loss:

data/lib/dotsync/actions/concerns/mappings_transfer.rb

@@ -23,8 +23,9 @@ module Dotsync
 
     MAPPINGS_LEGEND = [
       [Icons.force, "The source will overwrite the destination"],
-      [Icons.only, "Paths designated explicitly as source only"],
-      [Icons.ignore, "Paths configured to be ignored in the destination"],
+      [Icons.only, "Filtered by 'only' whitelist"],
+      [Icons.ignore, "Filtered by 'ignore' blacklist"],
+      [Icons.hook, "Post-sync hooks configured"],
       [Icons.invalid, "Invalid paths detected in the source or destination"]
     ]
 
@@ -135,6 +136,42 @@ module Dotsync
       end
     end
 
+    def execute_hooks
+      valid_mappings.each_with_index do |mapping, idx|
+        next unless mapping.has_hooks?
+
+        differ = differs[idx]
+        changed_files = differ.additions + differ.modifications
+        next if changed_files.empty?
+
+        runner = Dotsync::HookRunner.new(mapping: mapping, changed_files: changed_files, logger: logger)
+        runner.execute
+      end
+    end
+
+    def show_hooks_preview
+      hooks_to_run = []
+
+      valid_mappings.each_with_index do |mapping, idx|
+        next unless mapping.has_hooks?
+
+        differ = differs[idx]
+        changed_files = differ.additions + differ.modifications
+        next if changed_files.empty?
+
+        runner = Dotsync::HookRunner.new(mapping: mapping, changed_files: changed_files, logger: logger)
+        hooks_to_run.concat(runner.preview)
+      end
+
+      return if hooks_to_run.empty?
+
+      info("Hooks to run:", icon: :hook)
+      hooks_to_run.each do |command|
+        logger.log("  #{command}")
+      end
+      logger.log("")
+    end
+
     private
       # Computes diffs for all valid mappings.
       #

data/lib/dotsync/actions/pull_action.rb

@@ -16,6 +16,7 @@ module Dotsync
       show_mappings if output_sections[:mappings]
       show_differences_legend if has_differences? && output_sections[:differences_legend]
       show_differences(diff_content: output_sections[:diff_content]) if output_sections[:differences]
+      show_hooks_preview if output_sections[:differences]
 
       return unless options[:apply]
 
@@ -32,6 +33,7 @@ module Dotsync
       end
 
       transfer_mappings
+      execute_hooks
       action("Mappings pulled", icon: :done)
     end
 

data/lib/dotsync/actions/push_action.rb

@@ -14,6 +14,7 @@ module Dotsync
       show_mappings if output_sections[:mappings]
       show_differences_legend if has_differences? && output_sections[:differences_legend]
       show_differences(diff_content: output_sections[:diff_content]) if output_sections[:differences]
+      show_hooks_preview if output_sections[:differences]
 
       return unless options[:apply]
 
@@ -23,6 +24,7 @@ module Dotsync
       end
 
       transfer_mappings
+      execute_hooks
       action("Mappings pushed", icon: :done)
     end
   end

data/lib/dotsync/config/concerns/sync_mappings.rb

@@ -96,6 +96,12 @@ module Dotsync
         base["ignore"] = mapping["ignore"] if mapping.key?("ignore")
         base["only"] = mapping["only"] if mapping.key?("only")
 
+        # Resolve hooks for direction
+        if mapping.key?("hooks")
+          resolved = resolve_hooks_for_direction(mapping["hooks"], direction)
+          base["hooks"] = resolved if resolved.any?
+        end
+
         base
       end
 
@@ -142,9 +148,41 @@ module Dotsync
         base["ignore"] = mapping["ignore"] if mapping.key?("ignore")
         base["only"] = only if only
 
+        # Resolve hooks for direction
+        if mapping.key?("hooks")
+          resolved = resolve_hooks_for_direction(mapping["hooks"], direction)
+          base["hooks"] = resolved if resolved.any?
+        end
+
         base
       end
 
+      def resolve_hooks_for_direction(raw_hooks, direction)
+        return [] unless raw_hooks.is_a?(Hash)
+
+        hooks = Array(raw_hooks["post_sync"])
+        case direction
+        when :push
+          hooks += Array(raw_hooks["post_push"])
+        when :pull
+          hooks += Array(raw_hooks["post_pull"])
+        end
+        hooks
+      end
+
+      def validate_hooks!(hooks, context)
+        return unless hooks.is_a?(Hash)
+
+        valid_keys = %w[post_sync post_push post_pull]
+        invalid_keys = hooks.keys - valid_keys
+        return if invalid_keys.empty?
+
+        raise Dotsync::ConfigError,
+          "Configuration error in #{context}: " \
+          "Invalid hook key(s): #{invalid_keys.join(", ")}. " \
+          "Valid keys are: #{valid_keys.join(", ")}"
+      end
+
       def build_path(base, path)
         path ? File.join(base, path) : base
       end
@@ -171,6 +209,8 @@ module Dotsync
               "Configuration error in sync.mappings ##{index + 1}: " \
               "Each mapping must have 'local' and 'remote' keys."
           end
+
+          validate_hooks!(mapping["hooks"], "sync.mappings ##{index + 1}") if mapping.key?("hooks")
         end
       end
 
@@ -184,6 +224,8 @@ module Dotsync
                 "Configuration error in sync.#{shorthand_type} ##{index + 1}: " \
                 "Each mapping must be a table."
             end
+
+            validate_hooks!(mapping["hooks"], "sync.#{shorthand_type} ##{index + 1}") if mapping.is_a?(Hash) && mapping.key?("hooks")
           end
         end
       end

data/lib/dotsync/config/pull_action_config.rb

@@ -22,7 +22,15 @@ module Dotsync
 
       def section_mappings
         return [] unless section && section["mappings"]
-        Array(section["mappings"]).map { |mapping| Dotsync::Mapping.new(mapping) }
+        Array(section["mappings"]).map do |mapping|
+          attrs = mapping.dup
+          if attrs.key?("hooks") && attrs["hooks"].is_a?(Hash)
+            resolved = Array(attrs["hooks"]["post_pull"])
+            attrs["hooks"] = resolved.any? ? resolved : nil
+            attrs.delete("hooks") unless attrs["hooks"]
+          end
+          Dotsync::Mapping.new(attrs)
+        end
       end
 
       def validate!
@@ -46,6 +54,16 @@ module Dotsync
           unless mapping.is_a?(Hash) && mapping.key?("src") && mapping.key?("dest")
             raise "Configuration error in pull mapping ##{index + 1}: Each mapping must have 'src' and 'dest' keys."
           end
+
+          if mapping.is_a?(Hash) && mapping.key?("hooks") && mapping["hooks"].is_a?(Hash)
+            invalid_keys = mapping["hooks"].keys - ["post_pull"]
+            if invalid_keys.any?
+              raise Dotsync::ConfigError,
+                "Configuration error in pull mapping ##{index + 1}: " \
+                "Only 'post_pull' hooks are allowed in [pull] mappings. " \
+                "Invalid key(s): #{invalid_keys.join(", ")}"
+            end
+          end
         end
       end
   end

data/lib/dotsync/config/push_action_config.rb

@@ -17,7 +17,15 @@ module Dotsync
 
       def section_mappings
         return [] unless section && section["mappings"]
-        Array(section["mappings"]).map { |mapping| Dotsync::Mapping.new(mapping) }
+        Array(section["mappings"]).map do |mapping|
+          attrs = mapping.dup
+          if attrs.key?("hooks") && attrs["hooks"].is_a?(Hash)
+            resolved = Array(attrs["hooks"]["post_push"])
+            attrs["hooks"] = resolved.any? ? resolved : nil
+            attrs.delete("hooks") unless attrs["hooks"]
+          end
+          Dotsync::Mapping.new(attrs)
+        end
       end
 
       def validate!
@@ -41,6 +49,16 @@ module Dotsync
           unless mapping.is_a?(Hash) && mapping.key?("src") && mapping.key?("dest")
             raise "Configuration error in push mapping ##{index + 1}: Each mapping must have 'src' and 'dest' keys."
           end
+
+          if mapping.is_a?(Hash) && mapping.key?("hooks") && mapping["hooks"].is_a?(Hash)
+            invalid_keys = mapping["hooks"].keys - ["post_push"]
+            if invalid_keys.any?
+              raise Dotsync::ConfigError,
+                "Configuration error in push mapping ##{index + 1}: " \
+                "Only 'post_push' hooks are allowed in [push] mappings. " \
+                "Invalid key(s): #{invalid_keys.join(", ")}"
+            end
+          end
         end
       end
   end

data/lib/dotsync/errors.rb

@@ -8,4 +8,5 @@ module Dotsync
   class DiskFullError < FileTransferError; end
   class SymlinkError < FileTransferError; end
   class TypeConflictError < FileTransferError; end
+  class HookError < Error; end
 end

data/lib/dotsync/icons.rb

@@ -18,6 +18,7 @@ module Dotsync
     DEFAULT_ONLY = " "
     DEFAULT_IGNORE = "󰈉 "
     DEFAULT_INVALID = "󱏏 "
+    DEFAULT_HOOK = "󰜎 "
 
     # Default Mappings Differences icons
     DEFAULT_DIFF_CREATED = " "
@@ -50,6 +51,7 @@ module Dotsync
         only: config.dig("icons", "only") || DEFAULT_ONLY,
         ignore: config.dig("icons", "ignore") || DEFAULT_IGNORE,
         invalid: config.dig("icons", "invalid") || DEFAULT_INVALID,
+        hook: config.dig("icons", "hook") || DEFAULT_HOOK,
         # Differences Legend
         diff_created: config.dig("icons", "diff_created") || DEFAULT_DIFF_CREATED,
         diff_updated: config.dig("icons", "diff_updated") || DEFAULT_DIFF_UPDATED,
@@ -75,6 +77,10 @@ module Dotsync
       @custom_icons[:invalid] || DEFAULT_INVALID
     end
 
+    def self.hook
+      @custom_icons[:hook] || DEFAULT_HOOK
+    end
+
     # Differences Legend methods
 
     def self.diff_created
@@ -100,6 +106,7 @@ module Dotsync
       diff: DIFF,
       force: -> { force },
       ignore: -> { ignore },
+      hook: DEFAULT_HOOK,
       pull: PULL,
       push: PUSH,
       watch: WATCH,

data/lib/dotsync/loaders/pull_loader.rb

@@ -13,6 +13,7 @@ require_relative "../utils/directory_differ"
 require_relative "../utils/config_cache"
 require_relative "../utils/content_diff"
 require_relative "../utils/parallel"
+require_relative "../utils/hook_runner"
 
 # Models
 require_relative "../models/mapping"

data/lib/dotsync/loaders/push_loader.rb

@@ -13,6 +13,7 @@ require_relative "../utils/directory_differ"
 require_relative "../utils/config_cache"
 require_relative "../utils/content_diff"
 require_relative "../utils/parallel"
+require_relative "../utils/hook_runner"
 
 # Models
 require_relative "../models/mapping"

data/lib/dotsync/models/mapping.rb

@@ -29,6 +29,7 @@ module Dotsync
       @original_ignores = Array(attributes["ignore"])
       @original_only = Array(attributes["only"])
       @force = attributes["force"] || false
+      @hooks = Array(attributes["hooks"])
 
       @sanitized_src, @sanitized_dest, @sanitized_ignores, @sanitized_only = process_paths(
         @original_src,
@@ -58,6 +59,12 @@ module Dotsync
       @force
     end
 
+    attr_reader :hooks
+
+    def has_hooks?
+      @hooks.any?
+    end
+
     def directories?
       File.directory?(src) && File.directory?(dest)
     end
@@ -103,6 +110,7 @@ module Dotsync
       msg << Icons.force if force?
       msg << Icons.only if has_inclusions?
       msg << Icons.ignore if has_ignores?
+      msg << Icons.hook if has_hooks?
       msg << Icons.invalid unless valid?
       msg.join
     end

data/lib/dotsync/utils/hook_runner.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "open3"
+require "shellwords"
+
+module Dotsync
+  class HookRunner
+    def initialize(mapping:, changed_files:, logger:)
+      @mapping = mapping
+      @changed_files = changed_files
+      @logger = logger
+    end
+
+    def execute
+      @mapping.hooks.map do |command|
+        expanded = expand_template(command)
+        run_command(expanded)
+      end
+    end
+
+    def preview
+      @mapping.hooks.map { |command| expand_template(command) }
+    end
+
+    private
+      def expand_template(command)
+        files_str = @changed_files.map { |f| Shellwords.escape(f) }.join(" ")
+
+        command
+          .gsub("{files}", files_str)
+          .gsub("{src}", @mapping.src)
+          .gsub("{dest}", @mapping.dest)
+      end
+
+      def run_command(command)
+        stdout, stderr, status = Open3.capture3(command)
+
+        if status.success?
+          @logger.info("Hook succeeded: #{command}", icon: :hook)
+        else
+          @logger.error("Hook failed: #{command}")
+          @logger.error("  #{stderr.strip}") unless stderr.strip.empty?
+        end
+
+        { command: command, stdout: stdout, stderr: stderr, success: status.success? }
+      end
+  end
+end

data/lib/dotsync/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Dotsync
-  VERSION = "0.2.2"
+  VERSION = "0.2.3"
 end

data/lib/dotsync.rb

@@ -32,6 +32,7 @@ require_relative "dotsync/utils/directory_differ"
 require_relative "dotsync/utils/version_checker"
 require_relative "dotsync/utils/config_cache"
 require_relative "dotsync/utils/parallel"
+require_relative "dotsync/utils/hook_runner"
 
 # Models
 require_relative "dotsync/models/mapping"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dotsync
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors:
 - David Sáenz
@@ -337,6 +337,7 @@ files:
 - lib/dotsync/utils/content_diff.rb
 - lib/dotsync/utils/directory_differ.rb
 - lib/dotsync/utils/file_transfer.rb
+- lib/dotsync/utils/hook_runner.rb
 - lib/dotsync/utils/logger.rb
 - lib/dotsync/utils/parallel.rb
 - lib/dotsync/utils/path_utils.rb