gitflash 0.5.1 → 0.6.0

data/lib/gitflash/commands/undo.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Commands
+    # Restores a snapshot (the latest one by default). The current state is saved first,
+    # so an undo can itself be undone.
+    class Undo < Base
+      def call(id = nil)
+        snapshot = find(id)
+        return no_snapshots unless snapshot
+
+        check_worktree!(snapshot)
+        restore = Restore.new(snapshot)
+        plan = restore.plan.merge(snapshot: snapshot.id)
+        return nothing_to_undo(plan) if restore.empty?
+
+        restore!(snapshot, restore, plan)
+      end
+
+      private
+
+      def find(id)
+        return snapshots.list.first if id.nil?
+
+        snapshots.find(id) || usage_error!('unknown_snapshot', "Unknown snapshot '#{id}'")
+      end
+
+      # Branches are shared between worktrees; HEAD and files belong to one worktree
+      def check_worktree!(snapshot)
+        return unless snapshot.scope?('head') || snapshot.scope?('worktree')
+        return if snapshot.worktree_path == repo.toplevel
+
+        usage_error!('wrong_worktree', "Snapshot #{snapshot.id} was taken in " \
+                                       "#{snapshot.worktree_path}; run gitflash undo there")
+      end
+
+      def restore!(snapshot, restore, plan)
+        text = "snapshot #{snapshot.id}:\n#{describe(plan)}"
+        return planned(plan, "Would restore #{text}") if ui.dry_run?
+        return cancelled(plan) unless ui.confirm?(summary(snapshot, plan), plan: plan)
+
+        apply(snapshot, restore, plan)
+      end
+
+      def apply(snapshot, restore, plan)
+        before = snapshots.create(reason: "before undo #{snapshot.id}", scope: snapshot.scope,
+                                  branches: snapshot.branches.keys)
+        failure = restore.apply
+        raise_failure(failure, before, plan) if failure
+
+        ui.report(status: 'done', plan: plan, result: { snapshot: snapshot.id }, undo: before,
+                  text: "Restored snapshot #{snapshot.id}:\n#{describe(plan)}")
+      end
+
+      def raise_failure(failure, before, plan)
+        message = "gitflash undo failed:\n#{failure.output}\n" \
+                  "The state before this undo is saved as snapshot #{before.id}."
+        raise Error.new(message, code: 'git_failed', plan: plan)
+      end
+
+      def no_snapshots
+        ui.report(status: 'noop', result: { snapshot: nil }, text: 'No snapshots to undo')
+      end
+
+      def nothing_to_undo(plan)
+        text = "Nothing to undo: the repository already matches snapshot #{plan[:snapshot]}"
+        ui.report(status: 'noop', plan: plan, result: { snapshot: plan[:snapshot] }, text: text)
+      end
+
+      def summary(snapshot, plan)
+        "You are about to restore snapshot #{snapshot.id} " \
+          "(#{snapshot.reason}, #{snapshot.created_at}):\n#{describe(plan)}"
+      end
+
+      def describe(plan)
+        lines = plan[:branches].map { |change| branch_line(change) }
+        lines << head_line(plan[:head]) if plan[:head]
+        lines << '* restore tracked, staged and untracked files' if plan[:worktree]
+        lines << "* restore #{plan[:stashes].size} stash entries" if plan[:stashes].any?
+        lines.join("\n")
+      end
+
+      def branch_line(change)
+        target = change[:to][0, 7]
+        return "* recreate #{change[:branch]} at #{target}" unless change[:from]
+
+        "* move #{change[:branch]} back to #{target}"
+      end
+
+      def head_line(head)
+        "* switch HEAD from #{short(head[:from])} to #{short(head[:to])}"
+      end
+
+      def short(ref)
+        ref.to_s.match?(/\A\h{40}\z/) ? ref[0, 7] : ref.to_s
+      end
+    end
+  end
+end

data/lib/gitflash/git/bash_command.rb

@@ -8,16 +8,17 @@ module Gitflash
       class << self
         # Runs a command without a shell and returns its stdout.
         # Raises CommandError when the command exits with a non-zero status.
-        def exec(*args)
-          stdout, stderr, success = capture(*args)
+        def exec(*args, env: {})
+          stdout, stderr, success = capture(*args, env: env)
           raise CommandError, "#{args.join(' ')} failed: #{stderr.strip}" unless success
 
           stdout
         end
 
         # Runs a command without a shell and returns [stdout, stderr, success].
-        def capture(*args)
-          stdout, stderr, status = Open3.capture3(*args)
+        # `env` adds environment variables for this command only.
+        def capture(*args, env: {})
+          stdout, stderr, status = Open3.capture3(env, *args)
           [stdout, stderr, status.success?]
         rescue SystemCallError => e
           raise CommandError, "#{args.join(' ')} failed: #{e.message}"

data/lib/gitflash/hook/claude.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Gitflash
+  module Hook
+    # Claude Code PreToolUse hook for the Bash tool.
+    #
+    # Reads the hook input (JSON on stdin) and, when the command can lose work git cannot
+    # restore, acts according to the mode:
+    #   snapshot  save a snapshot and let the command run (default)
+    #   ask       save a snapshot and ask the user to approve the command
+    #   deny      block the command and point to the gitflash equivalent
+    # Returns the hook output as a Hash, or nil to leave the decision to Claude Code.
+    class Claude
+      MODES = %w[snapshot ask deny].freeze
+      EVENT = 'PreToolUse'
+
+      def initialize(mode: 'snapshot', snapshots: -> { Gitflash::Snapshots.new })
+        @mode = mode
+        @snapshots = snapshots
+      end
+
+      def call(input)
+        targets = targets(JSON.parse(input))
+        return nil if targets.empty?
+        return deny(targets) if @mode == 'deny'
+
+        saved = merge_by_dir(targets).filter_map { |target| save(target) }
+        saved.empty? ? nil : output(saved)
+      end
+
+      private
+
+      def targets(data)
+        return [] unless data['tool_name'] == 'Bash'
+
+        command = data.dig('tool_input', 'command').to_s
+        CommandParser.new(data['cwd'] || Dir.pwd).targets(command)
+      end
+
+      # One snapshot per directory, covering every command run there
+      def merge_by_dir(targets)
+        targets.group_by(&:dir).map do |dir, group|
+          CommandParser::Target.new(
+            dir: dir, command: group.map(&:command).join(' && '),
+            scope: group.flat_map(&:scope).uniq, branches: group.flat_map(&:branches).uniq
+          )
+        end
+      end
+
+      # [target, snapshot], or nil when the directory is not a git work tree
+      def save(target)
+        return nil unless Dir.exist?(target.dir)
+
+        Dir.chdir(target.dir) do
+          next nil unless git('rev-parse', '--is-inside-work-tree') == 'true'
+
+          snapshot = @snapshots.call.create(reason: "agent hook: before `#{target.command}`",
+                                            scope: target.scope, branches: branches(target))
+          [target, snapshot]
+        end
+      end
+
+      # Full ref shortened by removing refs/heads/ only; `--short` changes when a tag has the name
+      def current_branch
+        git('symbolic-ref', '--quiet', 'HEAD')&.delete_prefix(Repo::HEADS)
+      end
+
+      def branches(target)
+        target.branches.filter_map do |name|
+          name == :current ? current_branch : name
+        end
+      end
+
+      def output(saved)
+        notes = saved.map { |target, snap| "snapshot #{snap.id} before `#{target.command}`" }
+        context = "gitflash saved #{notes.join('; ')}. If this discards work that was still " \
+                  "needed, restore it with `gitflash undo #{saved.last[1].id}` " \
+                  '(list snapshots with `gitflash snapshots`).'
+        specific = { hookEventName: EVENT, additionalContext: context }
+        if @mode == 'ask'
+          specific[:permissionDecision] = 'ask'
+          specific[:permissionDecisionReason] =
+            "This command can discard work git cannot restore. #{context}"
+        end
+        { hookSpecificOutput: specific }
+      end
+
+      def deny(targets)
+        commands = targets.map { |target| "`#{target.command}`" }.join(', ')
+        reason = "gitflash blocked #{commands}: it can discard work git cannot restore. " \
+                 'Use the gitflash equivalent (gitflash reset, gitflash delete, ...), which ' \
+                 'saves a snapshot first, or run `gitflash snapshot` before retrying.'
+        { hookSpecificOutput: { hookEventName: EVENT, permissionDecision: 'deny',
+                                permissionDecisionReason: reason } }
+      end
+
+      # Stripped stdout of a git command, or nil when it fails
+      def git(*)
+        stdout, _stderr, success = Git::BashCommand.capture('git', *)
+        success ? stdout.strip : nil
+      end
+    end
+  end
+end

data/lib/gitflash/hook/command_parser.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module Gitflash
+  module Hook
+    # Finds git commands in a shell command line that can lose work git itself cannot restore:
+    # uncommitted or untracked files, deleted branches (their reflog is deleted with them) and
+    # dropped stashes. Commands that only add history (commit, merge, pull) are ignored because
+    # the reflog already covers them. See Rules for the list.
+    #
+    # The parser is deliberately simple: it splits on ; & | and newlines outside quotes, follows
+    # `cd DIR` and `git -C DIR`, and may report a command more often than needed. An extra
+    # snapshot is harmless; a missed one is not.
+    class CommandParser
+      # dir: where to take the snapshot; branches: names, or :current for the checked-out one
+      Target = Data.define(:dir, :command, :scope, :branches)
+
+      PREFIXES = %w[sudo command exec time nohup env].freeze
+      OPTIONS_WITH_VALUE = %w[-c --git-dir --work-tree --namespace --exec-path --config-env].freeze
+
+      def initialize(cwd)
+        @cwd = cwd
+      end
+
+      def targets(command_line)
+        dir = @cwd
+        segments(command_line).filter_map do |segment|
+          words = words(segment)
+          next if words.empty?
+
+          if words.first == 'cd'
+            dir = File.expand_path(words[1] || Dir.home, dir)
+            next
+          end
+          git_target(words, dir, segment.strip) if File.basename(words.first) == 'git'
+        end
+      end
+
+      private
+
+      # Splits on unquoted ; & | and newlines
+      def segments(line)
+        parts = [+'']
+        quote = nil
+        line.each_char do |char|
+          if quote
+            quote = nil if char == quote
+          elsif ["'", '"'].include?(char)
+            quote = char
+          elsif ";&|\n".include?(char)
+            parts << +''
+            next
+          end
+          parts.last << char
+        end
+        parts.reject { |part| part.strip.empty? }
+      end
+
+      # Shell words without subshell brackets, environment assignments and wrappers like sudo
+      def words(segment)
+        words = split(segment).map { |word| unwrap(word) }.reject(&:empty?)
+        words.shift while words.first && prefix?(words.first)
+        words
+      end
+
+      def prefix?(word)
+        PREFIXES.include?(word) || word.match?(/\A\w+=/)
+      end
+
+      def split(segment)
+        Shellwords.split(segment)
+      rescue ArgumentError
+        segment.split
+      end
+
+      def unwrap(word)
+        word.delete_prefix('(').delete_prefix('{').delete_suffix(')').delete_suffix('}')
+      end
+
+      def git_target(words, dir, command)
+        index, dir = skip_git_options(words, dir)
+        rule = Rules.for(words[index], words[(index + 1)..] || [], dir)
+        return nil unless rule
+
+        Target.new(dir: rule.fetch(:dir, dir), command: command, scope: rule[:scope],
+                   branches: rule[:branches] || [])
+      end
+
+      # Index of the subcommand, and the directory after any -C options
+      def skip_git_options(words, dir)
+        index = 1
+        while (option = words[index])&.start_with?('-')
+          dir = File.expand_path(words[index + 1].to_s, dir) if option == '-C'
+          index += option == '-C' || OPTIONS_WITH_VALUE.include?(option) ? 2 : 1
+        end
+        [index, dir]
+      end
+    end
+  end
+end

data/lib/gitflash/hook/rules.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Hook
+    # Which git subcommands can lose work git cannot restore, and what to save before them.
+    # Each rule takes the subcommand's arguments and the directory, and returns nil (safe) or
+    # { scope:, branches:, dir: } where branches may contain :current for the checked-out one.
+    module Rules
+      FULL = %w[branches head worktree].freeze
+
+      module_function
+
+      def for(subcommand, args, dir)
+        rule = RULES[subcommand]
+        rule&.call(args, dir)
+      end
+
+      def any?(args, flags)
+        args.intersect?(flags)
+      end
+
+      # `git checkout PATH` overwrites uncommitted changes in PATH without any flag, and telling a
+      # path from a branch needs git; an argument that names an existing file counts as a path.
+      def checkout(args, dir)
+        discards = any?(args, %w[-- . --force --patch --ours --theirs]) ||
+                   short_flags(args).match?(/[fp]/) || path_arg?(args, dir)
+        discards ? { scope: %w[worktree] } : nil
+      end
+
+      # The letters of all short options, so bundled ones such as `-fq` are seen
+      def short_flags(args)
+        args.select { |arg| arg.start_with?('-') && !arg.start_with?('--') }.join
+      end
+
+      def path_arg?(args, dir)
+        args.reject { |arg| arg.start_with?('-') }.any? do |arg|
+          File.exist?(File.expand_path(arg, dir))
+        end
+      end
+
+      def clean(args, _dir)
+        flags = args.select { |arg| arg.start_with?('-') }
+        short = short_flags(args)
+        force = flags.include?('--force') || short.include?('f')
+        dry_run = any?(flags, %w[--dry-run --interactive]) || short.match?(/[ni]/)
+        force && !dry_run ? { scope: %w[worktree] } : nil
+      end
+
+      def switch(args, _dir)
+        discards = any?(args, %w[--force --discard-changes]) || short_flags(args).include?('f')
+        discards ? { scope: %w[head worktree] } : nil
+      end
+
+      def stash(args, _dir)
+        case args.first
+        when 'drop', 'clear' then { scope: %w[stashes] }
+        when 'pop' then { scope: %w[worktree stashes] }
+        end
+      end
+
+      def branch(args, _dir)
+        return nil unless any?(args, %w[-d -D --delete -f --force -m -M --move -C --copy])
+
+        { scope: %w[branches], branches: args.reject { |arg| arg.start_with?('-') } }
+      end
+
+      def update_ref(args, _dir)
+        return nil unless args.include?('-d')
+
+        heads = args.select { |arg| arg.start_with?('refs/heads/') }
+        { scope: %w[branches], branches: heads.map { |ref| ref.delete_prefix('refs/heads/') } }
+      end
+
+      def rebase(args, _dir)
+        args.include?('--continue') ? nil : { scope: FULL, branches: [:current] }
+      end
+
+      def abort(args, _dir)
+        any?(args, %w[--abort --quit]) ? { scope: %w[worktree] } : nil
+      end
+
+      # `git worktree remove --force PATH` deletes that worktree's uncommitted files
+      def worktree(args, dir)
+        return nil unless args.first == 'remove' && any?(args, %w[-f --force])
+
+        path = args[1..].reject { |arg| arg.start_with?('-') }.first
+        path && { scope: %w[worktree], dir: File.expand_path(path, dir) }
+      end
+
+      RULES = {
+        'reset' => ->(_args, _dir) { { scope: FULL, branches: [:current] } },
+        'checkout' => method(:checkout),
+        'restore' => ->(_args, _dir) { { scope: %w[worktree] } },
+        'clean' => method(:clean),
+        'switch' => method(:switch),
+        'stash' => method(:stash),
+        'branch' => method(:branch),
+        'update-ref' => method(:update_ref),
+        'rebase' => method(:rebase),
+        'merge' => method(:abort),
+        'cherry-pick' => method(:abort),
+        'revert' => method(:abort),
+        'am' => method(:abort),
+        'worktree' => method(:worktree)
+      }.freeze
+    end
+  end
+end

data/lib/gitflash/hook/settings.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Gitflash
+  module Hook
+    # Where Claude Code reads the settings that can hold the gitflash hook, following its rules:
+    #   local    .claude/settings.local.json at the repository root (the main checkout's root
+    #            inside a linked worktree), for sessions started anywhere in the repository
+    #   project  .claude/settings.json in the directory a session starts in; gitflash uses the
+    #            repository's top level, so it applies to sessions started there
+    #   user     ~/.claude/settings.json, for every session
+    # Claude Code reloads these files in running sessions, so no restart is needed.
+    class Settings
+      SCOPES = %w[local project user].freeze
+      PATTERN = /\bgitflash hook claude\b/
+
+      # `repo` is nil outside a git repository; only the user scope applies there
+      def initialize(repo)
+        @repo = repo
+      end
+
+      def path(scope)
+        case scope
+        when 'user' then File.join(Dir.home, '.claude', 'settings.json')
+        when 'project' then File.join(@repo.toplevel, '.claude', 'settings.json')
+        else File.join(@repo.main_root, '.claude', 'settings.local.json')
+        end
+      end
+
+      # Which Claude Code sessions read the file of a scope
+      def applies_to(scope)
+        case scope
+        when 'user' then 'every Claude Code session'
+        when 'project' then "Claude Code sessions started in #{@repo.toplevel}"
+        else "Claude Code sessions in #{@repo.main_root} and its worktrees"
+        end
+      end
+
+      def scopes
+        @repo ? SCOPES : %w[user]
+      end
+
+      def read(path)
+        return {} unless File.exist?(path)
+
+        JSON.parse(File.read(path))
+      rescue JSON::ParserError => e
+        raise Error.new("#{path} is not valid JSON: #{e.message}", code: 'invalid_settings')
+      end
+
+      # The gitflash hook entry in parsed settings, or nil
+      def entry(settings)
+        groups = Array(settings.dig('hooks', 'PreToolUse'))
+        groups.flat_map { |group| Array(group['hooks']) }
+              .find { |hook| hook['command'].to_s.match?(PATTERN) }
+      end
+    end
+  end
+end

data/lib/gitflash/hook_cli.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'thor'
+
+module Gitflash
+  # `gitflash hook ...`: integrations that let agents keep using plain git safely
+  class HookCli < Thor
+    include CommandRunner
+
+    namespace 'hook'
+
+    def self.exit_on_failure?
+      true
+    end
+
+    desc 'claude', 'Run as a Claude Code PreToolUse hook (reads the hook input on stdin)'
+    long_desc <<~TEXT
+      Reads the Claude Code hook input on stdin. When the Bash command can discard work git
+      cannot restore (for example reset --hard, clean -f, checkout -- ., branch -D, stash drop),
+      it saves a snapshot first and tells Claude how to undo it.
+
+      --mode snapshot  save a snapshot and let the command run (default)
+      --mode ask       save a snapshot and ask the user to approve the command
+      --mode deny      block the command and point to the gitflash equivalent
+
+      Errors never block the command: they are printed to stderr and the hook exits with 0.
+    TEXT
+    option :mode, type: :string, default: 'snapshot', enum: Hook::Claude::MODES
+    def claude
+      output = Hook::Claude.new(mode: options[:mode]).call($stdin.read)
+      puts JSON.generate(output) if output
+    rescue StandardError => e
+      warn "gitflash hook: #{e.message}"
+    end
+
+    desc 'install', 'Register the gitflash hook in Claude Code settings'
+    long_desc <<~TEXT
+      Adds `gitflash hook claude` as a PreToolUse hook for Bash commands. Keeps the rest of the
+      settings file unchanged and does nothing when the hook is already installed.
+
+      --scope local    .claude/settings.local.json at the repository root (default, not
+                       committed); applies to sessions anywhere in the repository and its worktrees
+      --scope project  .claude/settings.json at the repository top level (shared with the team);
+                       applies to sessions started there
+      --scope user     ~/.claude/settings.json; applies to every session
+
+      Claude Code reloads settings files, so running sessions pick the hook up without a restart.
+      Check the result with `gitflash hook status`.
+
+      Accepts the global --json and --dry-run options after the subcommand: gitflash hook install --json
+    TEXT
+    option :scope, type: :string, default: 'local', enum: Commands::HookInstall::SCOPES
+    option :mode, type: :string, default: 'snapshot', enum: Hook::Claude::MODES
+    def install
+      run_command('hook install', Commands::HookInstall, repo_required: options[:scope] != 'user')
+    end
+
+    desc 'status', 'Show whether the gitflash hook protects Claude Code sessions here'
+    long_desc <<~TEXT
+      Lists the Claude Code settings files that apply to the current directory, whether each
+      holds the gitflash hook and which sessions it applies to, and whether the gitflash
+      executable the hook runs is on PATH. Works outside a git repository (user scope only).
+    TEXT
+    def status
+      run_command('hook status', Commands::HookStatus, repo_required: false)
+    end
+  end
+end

data/lib/gitflash/repo.rb

@@ -39,6 +39,16 @@ module Gitflash
       branches.find(&:current?)&.name
     end
 
+    def toplevel
+      @bash.exec('git', 'rev-parse', '--show-toplevel').strip
+    end
+
+    # Root of the main checkout; differs from toplevel inside a linked worktree
+    def main_root
+      common = @bash.exec('git', 'rev-parse', '--path-format=absolute', '--git-common-dir').strip
+      File.basename(common) == '.git' ? File.dirname(common) : toplevel
+    end
+
     # The branch that origin/HEAD points to, else main or master when present locally
     def default_branch
       return @default_branch if defined?(@default_branch)