vagrant-git-hooks 0.2.0

data/lib/vagrant-git-hooks/plugin.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "vagrant"
+require "i18n"
+
+require_relative "version"
+require_relative "helpers"
+require_relative "config"
+require_relative "command"
+require_relative "service"
+require_relative "util/git"
+
+module VagrantGitHooks
+  class Plugin < Vagrant.plugin("2")
+    name "vagrant-git-hooks"
+
+    description <<~DESC
+      Manage git hooks declaratively from your Vagrantfile. A husky replacement
+      that needs no Node/npm, only Vagrant: it installs hook scripts into the
+      repository's hooks directory with ownership markers and backups.
+    DESC
+
+    config(:git_hooks) do
+      Config
+    end
+
+    command("hooks") do
+      Command
+    end
+
+    %i[machine_action_up machine_action_provision machine_action_reload].each do |hook_name|
+      action_hook(:vgh_install, hook_name) do |hook|
+        hook.append(Action::Install)
+      end
+    end
+
+    action_hook(:vgh_uninstall, :machine_action_destroy) do |hook|
+      hook.prepend(Action::Uninstall)
+    end
+  end
+
+  module Action
+    class Install
+      def initialize(app, _env) = (@app = app)
+
+      def call(env)
+        UiHelpers.setup_i18n!
+        cfg = env[:machine].config.git_hooks
+        UiHelpers.setup_locale_from_config!(cfg)
+        ui   = env[:ui]
+        root = env[:machine].env.root_path.to_s
+
+        run(cfg, ui, root) if cfg.install_on_up
+      rescue StandardError => e
+        UiHelpers.error(env[:ui], "VGH: #{e.message}")
+      ensure
+        @app.call(env)
+      end
+
+      private
+
+      def run(cfg, ui, root)
+        unless Util::Git.available? && Util::Git.repo?(root)
+          UiHelpers.warn(ui, "#{UiHelpers.e(:warning)} #{UiHelpers.t("messages.not_a_repo")}")
+          return
+        end
+
+        res = Service.install!(root: root, cfg: cfg, ui: ui)
+        if res[:installed].empty? && res[:updated].empty?
+          UiHelpers.say(ui, "#{UiHelpers.e(:info)} #{UiHelpers.t("messages.no_hooks")}")
+          return
+        end
+
+        UiHelpers.say(ui, "#{UiHelpers.e(:success)} #{UiHelpers.t("messages.installed",
+                                                                  count: res[:installed].size + res[:updated].size)}")
+        return if res[:backed_up].empty?
+
+        UiHelpers.say(ui, "#{UiHelpers.e(:info)} #{UiHelpers.t("messages.backed_up",
+                                                               list: res[:backed_up].join(", "))}")
+      end
+    end
+
+    class Uninstall
+      def initialize(app, _env) = (@app = app)
+
+      def call(env)
+        UiHelpers.setup_i18n!
+        cfg = env[:machine].config.git_hooks
+        UiHelpers.setup_locale_from_config!(cfg)
+        ui   = env[:ui]
+        root = env[:machine].env.root_path.to_s
+
+        run(cfg, ui, root) if cfg.remove_on_destroy
+      rescue StandardError => e
+        UiHelpers.error(env[:ui], "VGH: #{e.message}")
+      ensure
+        @app.call(env)
+      end
+
+      private
+
+      def run(cfg, ui, root)
+        return unless Util::Git.available? && Util::Git.repo?(root)
+
+        res = Service.uninstall!(root: root, cfg: cfg, ui: ui)
+        return if res[:removed].empty? && res[:restored].empty?
+
+        UiHelpers.say(ui, "#{UiHelpers.e(:broom)} #{UiHelpers.t("messages.removed", count: res[:removed].size)}")
+      end
+    end
+  end
+end

data/lib/vagrant-git-hooks/service.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "util/git"
+require_relative "util/manifest"
+require_relative "util/installer"
+
+module VagrantGitHooks
+  module Service
+    module_function
+
+    # Builds installable hook entries from direct config and an optional source directory.
+    #
+    # @param cfg [VagrantGitHooks::Config] Plugin configuration.
+    # @param root [String, Pathname] Git repository root.
+    # @return [Array<Hash>] Hook entries consumed by the installer.
+    def entries_from_config(cfg, root)
+      entries = {}
+
+      (cfg.hooks || {}).each do |name, cmd|
+        entries[name.to_s] = { name: name.to_s, commands: cmd }
+      end
+
+      adopt_source(cfg, root, entries)
+      entries.values
+    end
+
+    def adopt_source(cfg, root, entries)
+      # Explicit Vagrantfile hooks win over hooks_source files with the same name.
+      src = cfg.hooks_source.to_s.strip
+      return if src.empty?
+
+      dir = File.absolute_path?(src) ? src : File.expand_path(src, root.to_s)
+      return unless File.directory?(dir)
+
+      Dir.children(dir).sort.each do |fname|
+        next unless Config::KNOWN_HOOKS.include?(fname)
+
+        path = File.join(dir, fname)
+        next unless File.file?(path)
+        next if entries.key?(fname)
+
+        entries[fname] = { name: fname, content: File.read(path) }
+      end
+    end
+
+    def installer_for(root, ui: nil)
+      Util::Installer.new(
+        hooks_dir: Util::Git.hooks_dir(root),
+        manifest: Util::Manifest.new(Util::Git.manifest_path(root)),
+        ui: ui
+      )
+    end
+
+    # Installs or updates hooks for a Git repository.
+    #
+    # @param root [String, Pathname] Git repository root.
+    # @param cfg [VagrantGitHooks::Config] Plugin configuration.
+    # @param ui [Object, nil] Optional Vagrant UI object.
+    # @param dry_run [Boolean] Whether to report planned changes without writing files.
+    # @return [Hash] Installation result.
+    def install!(root:, cfg:, ui: nil, dry_run: false)
+      installer_for(root, ui: ui).install(
+        entries_from_config(cfg, root),
+        fail_on_error: cfg.fail_on_error,
+        dry_run: dry_run
+      )
+    end
+
+    # Removes managed hooks and restores backed-up foreign hooks.
+    #
+    # @param root [String, Pathname] Git repository root.
+    # @param ui [Object, nil] Optional Vagrant UI object.
+    # @param dry_run [Boolean] Whether to report planned changes without writing files.
+    # @return [Hash] Uninstall result.
+    def uninstall!(root:, ui: nil, dry_run: false)
+      installer_for(root, ui: ui).uninstall(dry_run: dry_run)
+    end
+
+    # Reports hook installation status for configured and previously managed hooks.
+    #
+    # @param root [String, Pathname] Git repository root.
+    # @param cfg [VagrantGitHooks::Config] Plugin configuration.
+    # @return [Array<Hash>] Status rows keyed by hook name.
+    def status(root:, cfg:)
+      configured = entries_from_config(cfg, root).map { |e| e[:name].to_s }
+      installer_for(root).status(configured)
+    end
+  end
+end

data/lib/vagrant-git-hooks/util/git.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "verbose"
+
+module VagrantGitHooks
+  module Util
+    module Git
+      module_function
+
+      def available?
+        Verbose.log("git", "--version")
+        _out, _err, st = Open3.capture3("git", "--version")
+        st.success?
+      rescue StandardError
+        false
+      end
+
+      def repo?(root)
+        out, _err, st = capture(root, "rev-parse", "--is-inside-work-tree")
+        st.success? && out.strip == "true"
+      end
+
+      def toplevel(root)
+        out, _err, st = capture(root, "rev-parse", "--show-toplevel")
+        st.success? && !out.strip.empty? ? out.strip : nil
+      end
+
+      def hooks_dir(root)
+        resolve(root, "hooks") || File.join(toplevel(root) || root.to_s, ".git", "hooks")
+      end
+
+      def manifest_path(root)
+        resolve(root, "vagrant-git-hooks.json") ||
+          File.join(toplevel(root) || root.to_s, ".git", "vagrant-git-hooks.json")
+      end
+
+      def resolve(root, name)
+        out, _err, st = capture(root, "rev-parse", "--git-path", name)
+        return nil unless st.success?
+
+        path = out.strip
+        return nil if path.empty?
+
+        absolute?(path) ? path : File.expand_path(path, root.to_s)
+      end
+
+      def capture(root, *args)
+        Verbose.log("git", "-C", root.to_s, *args)
+        Open3.capture3("git", "-C", root.to_s, *args)
+      end
+
+      def absolute?(path)
+        File.absolute_path?(path)
+      end
+    end
+  end
+end

data/lib/vagrant-git-hooks/util/installer.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "time"
+require_relative "../hook_builder"
+
+module VagrantGitHooks
+  module Util
+    class Installer
+      BACKUP_SUFFIX = ".bak"
+
+      def initialize(hooks_dir:, manifest:, ui: nil)
+        @hooks_dir = hooks_dir.to_s
+        @manifest  = manifest
+        @ui        = ui
+      end
+
+      # Installs or updates managed Git hooks.
+      #
+      # Existing foreign hooks are backed up once before replacement. Managed
+      # hooks are updated in place and tracked in the manifest by SHA-256 digest.
+      #
+      # @param entries [Array<Hash>] Hook definitions with `:name` and either `:commands` or `:content`.
+      # @param fail_on_error [Boolean] Whether generated hooks should include `set -e`.
+      # @param dry_run [Boolean] Whether to report planned changes without writing files.
+      # @return [Hash] Installation result with installed, updated, backed_up, and dry_run keys.
+      def install(entries, fail_on_error: true, dry_run: false)
+        FileUtils.mkdir_p(@hooks_dir) unless dry_run
+        data = @manifest.load
+        data["hooks_dir"] = @hooks_dir
+        managed = data["managed"]
+        result  = { installed: [], updated: [], backed_up: [], dry_run: dry_run }
+
+        entries.each do |entry|
+          name   = entry[:name].to_s
+          script = build(entry, fail_on_error)
+          path   = File.join(@hooks_dir, name)
+          ours   = File.exist?(path) && HookBuilder.managed?(safe_read(path))
+
+          backup = backup_if_foreign(path, name, ours, managed, result, dry_run)
+          write_hook(path, script) unless dry_run
+
+          (ours ? result[:updated] : result[:installed]) << name
+          managed[name] = {
+            "backup" => backup,
+            "sha256" => Digest::SHA256.hexdigest(script),
+            "installed_at" => now
+          }
+        end
+
+        @manifest.save(data) unless dry_run
+        result
+      end
+
+      # Removes managed hooks and restores backups recorded in the manifest.
+      #
+      # @param dry_run [Boolean] Whether to report planned changes without writing files.
+      # @return [Hash] Uninstall result with removed, restored, and dry_run keys.
+      def uninstall(dry_run: false)
+        data    = @manifest.load
+        base    = data["hooks_dir"] || @hooks_dir
+        result  = { removed: [], restored: [], dry_run: dry_run }
+
+        data["managed"].each do |name, info|
+          path = File.join(base, name)
+
+          if File.exist?(path) && HookBuilder.managed?(safe_read(path))
+            File.delete(path) unless dry_run
+            result[:removed] << name
+          end
+
+          backup = info["backup"]
+          next unless backup && File.exist?(backup)
+
+          restore(backup, path) unless dry_run
+          result[:restored] << name
+        end
+
+        @manifest.clear unless dry_run
+        result
+      end
+
+      # Reports whether hooks are installed, modified, foreign, or missing.
+      #
+      # @param configured_names [Array<String>] Hook names configured in the current Vagrantfile.
+      # @return [Array<Hash>] Status rows with name, state, and backup fields.
+      def status(configured_names = [])
+        data    = @manifest.load
+        base    = data["hooks_dir"] || @hooks_dir
+        managed = data["managed"]
+        names   = (managed.keys + configured_names.map(&:to_s)).uniq.sort
+
+        names.map do |name|
+          { name: name, state: state_of(File.join(base, name), managed[name]), backup: managed.dig(name, "backup") }
+        end
+      end
+
+      private
+
+      def build(entry, fail_on_error)
+        if entry[:content]
+          HookBuilder.adopt_script(name: entry[:name].to_s, content: entry[:content])
+        else
+          HookBuilder.script_for(name: entry[:name].to_s, commands: entry[:commands], fail_on_error: fail_on_error)
+        end
+      end
+
+      def backup_if_foreign(path, name, ours, managed, result, dry_run)
+        # Do not overwrite an existing backup: it is the user's original hook,
+        # not a rolling history of plugin-generated updates.
+        existing = managed.dig(name, "backup")
+        return existing unless File.exist?(path) && !ours && existing.nil?
+
+        backup = "#{path}#{BACKUP_SUFFIX}"
+        return backup if File.exist?(backup)
+
+        FileUtils.cp(path, backup) unless dry_run
+        result[:backed_up] << name
+        backup
+      end
+
+      def write_hook(path, script)
+        File.write(path, script)
+        File.chmod(0o755, path) unless Gem.win_platform?
+      end
+
+      def restore(backup, path)
+        FileUtils.mv(backup, path)
+        File.chmod(0o755, path) unless Gem.win_platform?
+      end
+
+      def state_of(path, info)
+        # A managed hook with a changed digest is still ours, but status reports
+        # it as modified so users can spot manual edits.
+        return "missing" unless File.exist?(path)
+        return "foreign" unless HookBuilder.managed?(safe_read(path))
+
+        if info && Digest::SHA256.hexdigest(safe_read(path)) != info["sha256"]
+          "modified"
+        else
+          "installed"
+        end
+      end
+
+      def safe_read(path)
+        File.read(path)
+      rescue StandardError
+        ""
+      end
+
+      def now
+        Time.now.utc.iso8601
+      rescue StandardError
+        Time.now.utc.to_s
+      end
+    end
+  end
+end

data/lib/vagrant-git-hooks/util/manifest.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module VagrantGitHooks
+  module Util
+    class Manifest
+      attr_reader :path
+
+      def initialize(path)
+        @path = path.to_s
+      end
+
+      # Loads the hook manifest from disk.
+      #
+      # Invalid or missing manifest data is treated as empty so hook commands can
+      # recover from interrupted runs.
+      #
+      # @return [Hash] Normalized manifest data.
+      def load
+        return empty unless File.exist?(@path)
+
+        data = JSON.parse(File.read(@path))
+        data.is_a?(Hash) ? normalize(data) : empty
+      rescue StandardError
+        empty
+      end
+
+      # Saves normalized hook manifest data.
+      #
+      # @param data [Hash] Manifest data.
+      # @return [Hash] Original data argument.
+      def save(data)
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.write(@path, JSON.pretty_generate(normalize(data)))
+        data
+      end
+
+      def clear
+        File.delete(@path) if File.exist?(@path)
+        true
+      rescue StandardError
+        false
+      end
+
+      private
+
+      def empty
+        { "hooks_dir" => nil, "managed" => {} }
+      end
+
+      def normalize(data)
+        {
+          "hooks_dir" => data["hooks_dir"],
+          "managed" => (data["managed"].is_a?(Hash) ? data["managed"] : {})
+        }
+      end
+    end
+  end
+end

data/lib/vagrant-git-hooks/util/verbose.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+module VagrantGitHooks
+  module Util
+    module Verbose
+      module_function
+
+      def enabled?
+        ENV["VGH_VERBOSE"].to_s == "1"
+      end
+
+      def log(*args)
+        return unless enabled?
+
+        line = args.length == 1 && args.first.is_a?(String) ? args.first : args.map(&:to_s).shelljoin
+        warn("[VGH] #{line}")
+      end
+    end
+  end
+end

data/lib/vagrant-git-hooks/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module VagrantGitHooks
+  unless defined?(VERSION)
+    VERSION = begin
+      path = File.expand_path("VERSION", __dir__)
+      File.exist?(path) ? File.read(path).strip : "0.0.0"
+    rescue StandardError
+      "0.0.0"
+    end
+  end
+end

data/lib/vagrant-git-hooks.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "vagrant-git-hooks/version"
+require_relative "vagrant-git-hooks/plugin"

data/locales/en.yml

@@ -0,0 +1,76 @@
+en:
+  vgh:
+    emoji:
+      success:  "✅"
+      info:     "🔍"
+      ongoing:  "🔁"
+      warning:  "⚠️"
+      error:    "❌"
+      version:  "💾"
+      broom:    "🧹"
+      question: "❓"
+    messages:
+      not_a_repo: "Not a git repository — skipping git hooks."
+      no_hooks: "No git hooks configured."
+      installed: "%{count} git hook(s) installed."
+      backed_up: "Backed up pre-existing hook(s): %{list}."
+      removed: "%{count} managed git hook(s) removed."
+      restored: "%{count} pre-existing hook(s) restored."
+      list_header: "Git hooks managed by the plugin:"
+    usage:
+      banner: "Usage: vagrant hooks <install|uninstall|list|run|version|help> [options]"
+      run: "Usage: vagrant hooks run <hook> [args...]"
+    errors:
+      unknown_command: "Unknown command. Try: vagrant hooks help."
+      no_machine: "No target machine found. Run this inside a Vagrant project or pass a VM name."
+      not_a_repo: "Not a git repository. Run this inside a git working tree."
+      cancelled: "Cancelled by user."
+      confirmation_required: "Confirmation required: pass --yes to proceed in --json mode."
+      hook_not_configured: "Hook '%{name}' is not configured in this Vagrantfile."
+    prompts:
+      uninstall: "This will remove all managed git hooks and restore backups. Continue? [y/N]"
+    log:
+      version_line: "v%{version}."
+    help:
+      general_title: "Usage: vagrant hooks <command> [args] [options]"
+      commands:
+        install:   "hooks install            Install configured hooks into .git/hooks"
+        uninstall: "hooks uninstall          Remove managed hooks and restore backups"
+        list:      "hooks list               Show managed hooks and their state"
+        run:       "hooks run <hook> [args]  Run a configured hook on demand (host)"
+        version:   "hooks version            Print the plugin version"
+        help:      "hooks help [TOPIC]       Show this help or a subcommand's help"
+      topic:
+        install: |
+          🔧 Help: vagrant hooks install
+            Usage:
+              vagrant hooks install [--dry-run] [--json]
+            Description:
+              Writes each configured hook into the repository hooks directory with a
+              managed header. A pre-existing, non-managed hook is backed up to
+              <hook>.bak before being replaced.
+        uninstall: |
+          🧹 Help: vagrant hooks uninstall
+            Usage:
+              vagrant hooks uninstall [--yes] [--json]
+            Description:
+              Removes hooks managed by the plugin and restores any <hook>.bak backup.
+        list: |
+          📋 Help: vagrant hooks list
+            Usage:
+              vagrant hooks list [--json]
+            Description:
+              Shows each hook with its state: installed, missing, modified, or foreign.
+        run: |
+          ▶️  Help: vagrant hooks run
+            Usage:
+              vagrant hooks run <hook> [args...]
+            Description:
+              Executes a configured hook on the host, useful for testing it without
+              making a commit.
+        version: |
+          💾 Help: vagrant hooks version
+            Usage:
+              vagrant hooks version [--json]
+            Description:
+              Prints the plugin version.

data/locales/fr.yml

@@ -0,0 +1,75 @@
+fr:
+  vgh:
+    emoji:
+      success:  "✅"
+      info:     "🔍"
+      ongoing:  "🔁"
+      warning:  "⚠️"
+      error:    "❌"
+      version:  "💾"
+      broom:    "🧹"
+      question: "❓"
+    messages:
+      not_a_repo: "Pas un dépôt git — hooks ignorés."
+      no_hooks: "Aucun hook git configuré."
+      installed: "%{count} hook(s) git installé(s)."
+      backed_up: "Hook(s) préexistant(s) sauvegardé(s) : %{list}."
+      removed: "%{count} hook(s) git géré(s) supprimé(s)."
+      restored: "%{count} hook(s) préexistant(s) restauré(s)."
+      list_header: "Hooks git gérés par le plugin :"
+    usage:
+      banner: "Utilisation : vagrant hooks <install|uninstall|list|run|version|help> [options]"
+      run: "Utilisation : vagrant hooks run <hook> [args...]"
+    errors:
+      unknown_command: "Commande inconnue. Essayez : vagrant hooks help."
+      no_machine: "Aucune machine cible. Lancez ceci dans un projet Vagrant ou passez un nom de VM."
+      not_a_repo: "Pas un dépôt git. Lancez ceci dans une copie de travail git."
+      cancelled: "Annulé par l'utilisateur."
+      confirmation_required: "Confirmation requise : ajoutez --yes pour confirmer en mode --json."
+      hook_not_configured: "Le hook '%{name}' n'est pas configuré dans ce Vagrantfile."
+    prompts:
+      uninstall: "Ceci supprimera tous les hooks gérés et restaurera les sauvegardes. Continuer ? [y/N]"
+    log:
+      version_line: "v%{version}."
+    help:
+      general_title: "Utilisation : vagrant hooks <commande> [args] [options]"
+      commands:
+        install:   "hooks install            Installe les hooks configurés dans .git/hooks"
+        uninstall: "hooks uninstall          Supprime les hooks gérés et restaure les sauvegardes"
+        list:      "hooks list               Affiche les hooks gérés et leur état"
+        run:       "hooks run <hook> [args]  Exécute un hook configuré à la demande (hôte)"
+        version:   "hooks version            Affiche la version du plugin"
+        help:      "hooks help [SUJET]       Affiche cette aide ou celle d'une sous-commande"
+      topic:
+        install: |
+          🔧 Aide : vagrant hooks install
+            Utilisation :
+              vagrant hooks install [--dry-run] [--json]
+            Description :
+              Écrit chaque hook configuré dans le dossier de hooks du dépôt avec un
+              en-tête géré. Un hook préexistant non géré est sauvegardé en
+              <hook>.bak avant d'être remplacé.
+        uninstall: |
+          🧹 Aide : vagrant hooks uninstall
+            Utilisation :
+              vagrant hooks uninstall [--yes] [--json]
+            Description :
+              Supprime les hooks gérés par le plugin et restaure toute sauvegarde <hook>.bak.
+        list: |
+          📋 Aide : vagrant hooks list
+            Utilisation :
+              vagrant hooks list [--json]
+            Description :
+              Affiche chaque hook avec son état : installed, missing, modified ou foreign.
+        run: |
+          ▶️  Aide : vagrant hooks run
+            Utilisation :
+              vagrant hooks run <hook> [args...]
+            Description :
+              Exécute un hook configuré sur l'hôte, utile pour le tester sans commit.
+        version: |
+          💾 Aide : vagrant hooks version
+            Utilisation :
+              vagrant hooks version [--json]
+            Description :
+              Affiche la version du plugin.