gitflash 0.7.0.beta2 → 0.7.0.beta3

data/lib/gitflash/hook/command_words.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module Gitflash
+  module Hook
+    # The words of one command: without subshell brackets, redirections, keywords like `then`,
+    # environment assignments and wrappers like `sudo -u me`
+    class CommandWords
+      # Shell words that can come before a command: `if git ...`, `then git ...`, `! git ...`
+      KEYWORDS = %w[if then else elif do while until ! {].freeze
+      REDIRECTION = /\A\d*(?:[<>]{1,2}|&>)/
+      # A redirection whose target is the next word (`>`, `2>>`), not part of it (`>out`)
+      BARE_REDIRECTION = /#{REDIRECTION}\z/
+      ASSIGNMENT = /\A\w+=/
+
+      # words: the command and its arguments; env: the assignments before it, as a Hash;
+      # chdir: the directory a wrapper switches to (`sudo -D DIR`, `env -C DIR`), or nil
+      attr_reader :words, :env, :chdir
+
+      def initialize(segment)
+        @env = {}
+        @chdir = nil
+        @words = strip(without_redirections(split(segment).map { |word| unwrap(word) }))
+      end
+
+      private
+
+      def strip(words)
+        loop do
+          words = strip_assignments(words.drop_while { |word| KEYWORDS.include?(word) })
+          stripped, dir = Wrappers.strip(words)
+          return words if stripped == words
+
+          words = stripped
+          @chdir = dir || @chdir
+        end
+      end
+
+      def strip_assignments(words)
+        while (word = words.first)&.match?(ASSIGNMENT)
+          name, value = word.split('=', 2)
+          @env[name] = value
+          words = words.drop(1)
+        end
+        words
+      end
+
+      # Drops `> file`, `2>&1`, `< list` and the like, which are not arguments
+      def without_redirections(words)
+        skip = false
+        words.reject do |word|
+          next (skip = false) || true if skip
+
+          skip = word.match?(BARE_REDIRECTION)
+          word.match?(REDIRECTION)
+        end
+      end
+
+      def split(segment)
+        Shellwords.split(segment)
+      rescue ArgumentError
+        segment.split
+      end
+
+      # Subshell brackets stuck to a word: `(cd x` and `y)`. Braces are words of their own in
+      # the shell (`{ git ...; }`), and `{}` is a placeholder for find and xargs
+      def unwrap(word)
+        word.delete_prefix('(').delete_suffix(')')
+      end
+    end
+  end
+end

data/lib/gitflash/hook/failure.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Gitflash
+  module Hook
+    # What the PreToolUse hook outputs when it fails: in ask and deny mode the command is asked
+    # about or blocked, because letting it run would turn the user's protection off; in snapshot
+    # mode it runs, as it would without the hook. PostToolUse runs after the command, so there is
+    # nothing left to decide.
+    module Failure
+      module_function
+
+      # The hook output as a Hash, or nil to leave the decision to Claude Code
+      def output(mode, error, input)
+        return nil if mode == 'snapshot' || post_event?(input)
+
+        { hookSpecificOutput: { hookEventName: Claude::EVENT, permissionDecision: mode,
+                                permissionDecisionReason: Messages.failure(error) } }
+      end
+
+      def post_event?(input)
+        JSON.parse(input)['hook_event_name'] == Claude::POST_EVENT
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/gitflash/hook/git_invocation.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module Gitflash
+  module Hook
+    # Reads `git [global options] SUBCOMMAND ARGS` the way git does: `-C`, `--git-dir`,
+    # `--work-tree` and `GIT_DIR` / `GIT_WORK_TREE` decide the repository, and an alias (from
+    # `-c alias.NAME=...` or the repository's config) is replaced by what it stands for.
+    class GitInvocation
+      # dir: the work tree git uses; script: the shell command of a `!` alias, else nil
+      Parsed = Data.define(:dir, :subcommand, :args, :script)
+
+      VALUE_OPTIONS = %w[-C -c --git-dir --work-tree --namespace --exec-path --config-env
+                         --super-prefix].freeze
+      MAX_ALIAS_DEPTH = 10
+      DIR_OPTIONS = { '-C' => :dir, '--git-dir' => :git_dir, '--work-tree' => :work_tree }.freeze
+
+      # Aliases from `git config` in the directory, as { name => value }; none when it is not a
+      # repository
+      def self.configured_aliases(dir)
+        stdout, _stderr, success = Git::BashCommand.capture('git', '-C', dir, 'config', '-z',
+                                                            '--get-regexp', '^alias\\.')
+        return {} unless success
+
+        stdout.split("\0").to_h do |entry|
+          key, value = entry.split("\n", 2)
+          [key.delete_prefix('alias.'), value.to_s]
+        end
+      end
+
+      # `dir_after` resolves a path against a directory (CommandParser's rules for paths the
+      # shell decides); `aliases` returns the configured aliases of a directory
+      def initialize(dir_after:, aliases:)
+        @dir_after = dir_after
+        @aliases = aliases
+      end
+
+      def parse(words, dir, env = {})
+        index, options = read_options(words, { dir: dir, aliases: {} })
+        dir = repository_dir(options, env)
+        subcommand = words[index]
+        args = words[(index + 1)..] || []
+        resolve(Parsed.new(dir:, subcommand:, args:, script: nil), options[:aliases])
+      end
+
+      private
+
+      # Index of the subcommand, and what the global options say
+      def read_options(words, options)
+        index = 1
+        while (option = words[index])&.start_with?('-')
+          name, value = option.split('=', 2)
+          takes_next = value.nil? && VALUE_OPTIONS.include?(name)
+          apply(options, name, takes_next ? words[index + 1].to_s : value.to_s)
+          index += takes_next ? 2 : 1
+        end
+        [index, options]
+      end
+
+      def apply(options, name, value)
+        if (key = DIR_OPTIONS[name])
+          options[key] = @dir_after.call(value, options[:dir])
+        elsif name == '-c' && value.start_with?('alias.')
+          alias_name, expansion = value.delete_prefix('alias.').split('=', 2)
+          options[:aliases][alias_name] = expansion.to_s
+        end
+      end
+
+      # The work tree git uses: --work-tree or GIT_WORK_TREE, else the one --git-dir or GIT_DIR
+      # belongs to, else the directory after -C
+      def repository_dir(options, env)
+        work_tree = options[:work_tree] || from_env(env, 'GIT_WORK_TREE', options)
+        return work_tree if work_tree
+
+        git_dir = options[:git_dir] || from_env(env, 'GIT_DIR', options)
+        return options[:dir] unless git_dir
+
+        File.basename(git_dir) == '.git' ? File.dirname(git_dir) : git_dir
+      end
+
+      def from_env(env, name, options)
+        env[name] && @dir_after.call(env[name], options[:dir])
+      end
+
+      # Git never lets an alias replace a built-in command
+      def alias_for(subcommand, inline, dir)
+        return nil if subcommand.nil? || CommandParser::BUILTINS.include?(subcommand)
+
+        inline[subcommand] || @aliases.call(dir)[subcommand]
+      end
+
+      # Follows an alias to what it stands for, and an alias of an alias, as git does (bounded,
+      # so an alias loop cannot hang the hook)
+      def resolve(parsed, inline)
+        MAX_ALIAS_DEPTH.times do
+          expansion = parsed.script ? nil : alias_for(parsed.subcommand, inline, parsed.dir)
+          return parsed unless expansion
+
+          parsed = expand(expansion, parsed.args, parsed.dir)
+        end
+        parsed
+      end
+
+      # `!cmd` aliases run in the shell; others are git arguments
+      def expand(expansion, args, dir)
+        if expansion.start_with?('!')
+          script = [expansion.delete_prefix('!'), *args].join(' ')
+          return Parsed.new(dir:, subcommand: nil, args: [], script:)
+        end
+
+        words = Shellwords.split(expansion) + args
+        Parsed.new(dir:, subcommand: words.first, args: words.drop(1), script: nil)
+      rescue ArgumentError
+        Parsed.new(dir:, subcommand: nil, args: [], script: nil)
+      end
+    end
+  end
+end

data/lib/gitflash/hook/history_rules.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Hook
+    # Rules for the less common git commands that lose work: plumbing that overwrites files,
+    # commands that delete the reflog or unreachable objects `gitflash undo` and git rely on,
+    # and branch deletion through `git push .`. Same contract as Rules.
+    module HistoryRules
+      FULL = %w[branches head worktree].freeze
+      WORKTREE = { scope: %w[worktree] }.freeze
+      PRUNE_NOW = /\A--prune=(?:now|all)\z/
+
+      module_function
+
+      # `git rm -f` drops uncommitted changes in the files it removes
+      def rm(args, _dir)
+        forced = args.include?('--force') || Rules.short_flags(args).include?('f')
+        forced && !args.include?('--cached') ? WORKTREE : nil
+      end
+
+      # `git checkout-index -f` overwrites files in the working tree
+      def checkout_index(args, _dir)
+        args.include?('--force') || Rules.short_flags(args).include?('f') ? WORKTREE : nil
+      end
+
+      # `git read-tree -u --reset` overwrites the working tree with the tree it reads
+      def read_tree(args, _dir)
+        args.include?('-u') && args.include?('--reset') ? WORKTREE : nil
+      end
+
+      # Expiring or deleting reflog entries drops the record of where branches were; the
+      # snapshot keeps their current tips reachable
+      def reflog(args, _dir)
+        %w[expire delete].include?(args.first) ? { scope: FULL } : nil
+      end
+
+      # Pruning unreachable objects now removes commits only the reflog still pointed at
+      def gc(args, _dir)
+        args.any? { |arg| arg.match?(PRUNE_NOW) } ? { scope: FULL } : nil
+      end
+
+      def prune(_args, _dir)
+        { scope: FULL }
+      end
+
+      # `git push . :branch`, `git push . --delete branch`: deletes a branch of this repository
+      def push(args, _dir)
+        positional = args.reject { |arg| arg.start_with?('-') }
+        return nil unless positional.first == '.'
+
+        names = deleted_refs(args, positional.drop(1))
+        return nil if names.nil?
+
+        # Names the shell or xargs fills in are unknown: save every branch
+        names = [] if names.any? { |name| Paths.unresolved?(name) || name.include?('{}') }
+        { scope: %w[branches], branches: names }
+      end
+
+      # Branch names a local push deletes: every ref with --delete, else the `:ref` ones.
+      # [] when --delete names no refs (they come from stdin, as with xargs): every branch is
+      # saved; nil when the push deletes nothing
+      def deleted_refs(args, refs)
+        delete = args.include?('--delete') || Rules.short_flags(args).include?('d')
+        refs = refs.select { |ref| ref.start_with?(':') } unless delete
+        return nil if refs.empty? && !delete
+
+        refs.map { |ref| ref.delete_prefix(':').delete_prefix(Repo::HEADS) }
+      end
+
+      RULES = {
+        'rm' => method(:rm),
+        'checkout-index' => method(:checkout_index),
+        'read-tree' => method(:read_tree),
+        'reflog' => method(:reflog),
+        'gc' => method(:gc),
+        'prune' => method(:prune),
+        'push' => method(:push)
+      }.freeze
+    end
+  end
+end

data/lib/gitflash/hook/losses.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Hook
+    # What a snapshot cannot bring back: ignored files a command deletes (`git clean -x`,
+    # `git worktree remove`) and untracked files too large to save. The hook names them so the
+    # agent is not told everything can be undone.
+    module Losses
+      SHOWN = 5
+
+      module_function
+
+      # A note for Claude about the targets and snapshots, or nil when nothing is lost for good
+      def note(saved, targets)
+        notes = targets.select(&:ignored).filter_map { |target| ignored_note(target) }
+        notes += saved.filter_map { |_target, snapshot| skipped_note(snapshot) }
+        notes.empty? ? nil : notes.join(' ')
+      end
+
+      def ignored_note(target)
+        files = ignored_files(target.dir)
+        return nil if files.empty?
+
+        "`#{target.command}` also deletes ignored files in #{target.dir}, which no snapshot " \
+          "saves: #{listing(files)}."
+      end
+
+      def skipped_note(snapshot)
+        return nil if snapshot.skipped_files.empty?
+
+        "Snapshot #{snapshot.id} left out untracked files over 50 MB, which cannot be restored: " \
+          "#{listing(snapshot.skipped_files)}."
+      end
+
+      # Ignored files and directories git reports in the directory (a whole ignored directory is
+      # one entry)
+      def ignored_files(dir)
+        stdout, _stderr, success = Git::BashCommand.capture(
+          'git', '-C', dir, 'ls-files', '-z', '--others', '--ignored', '--exclude-standard',
+          '--directory'
+        )
+        success ? stdout.split("\0") : []
+      end
+
+      def listing(files)
+        shown = files.first(SHOWN).map { |file| TerminalText.line(file) }.join(', ')
+        files.size > SHOWN ? "#{shown} and #{files.size - SHOWN} more" : shown
+      end
+    end
+  end
+end

data/lib/gitflash/hook/messages.rb

@@ -6,6 +6,15 @@ module Gitflash
     module Messages
       module_function
 
+      # Everything the hook tells Claude about the commands it saved ([target, snapshot] pairs)
+      # and the ones it could not save
+      def context(saved, unsaved)
+        targets = saved.map(&:first) + unsaved
+        guessed = targets.select(&:guessed)
+        [(saved(saved) unless saved.empty?), (unsaved(unsaved) unless unsaved.empty?),
+         (guessed(guessed) unless guessed.empty?), Losses.note(saved, targets)].compact.join(' ')
+      end
+
       def saved(saved)
         notes = saved.map { |target, snap| "snapshot #{snap.id} before `#{target.command}`" }
         "gitflash saved #{notes.join('; ')}. If this discards work that was still needed, " \
@@ -20,8 +29,20 @@ module Gitflash
       end
 
       def unsaved(targets)
-        "gitflash could not save a snapshot before #{commands(targets)} (the directory is not a " \
-          'git work tree or does not exist), so nothing can be restored with `gitflash undo`.'
+        dirs = targets.map(&:dir).uniq.join(', ')
+        "gitflash could not save a snapshot before #{commands(targets)} in #{dirs} (not a git " \
+          'work tree, does not exist, or the snapshot failed), so nothing it discards there can ' \
+          'be restored with `gitflash undo`. Run `gitflash snapshot` in that repository first ' \
+          'if the work matters.'
+      end
+
+      # The directory of these commands is decided by the shell (`cd "$REPO"`, `git -C "$X"`),
+      # so the snapshot was taken where Claude runs and may not cover what they change
+      def guessed(targets)
+        "The shell decides where #{commands(targets)} runs, so gitflash could only guess the " \
+          "directory (#{targets.map(&:dir).uniq.join(', ')}). If the command changes another " \
+          'repository, nothing it discards there can be restored; run `gitflash snapshot` in ' \
+          'that repository first if the work matters.'
       end
 
       def denial(targets)
@@ -30,6 +51,11 @@ module Gitflash
           'saves a snapshot first, or run `gitflash snapshot` before retrying.'
       end
 
+      def failure(error)
+        "gitflash could not check this command (#{error.message}), so it cannot tell whether " \
+          'it discards work git cannot restore. Run `gitflash snapshot` first if it might.'
+      end
+
       def commands(targets)
         targets.map { |target| "`#{target.command}`" }.join(', ')
       end

data/lib/gitflash/hook/paths.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Hook
+    # How the hook reads a path from a command line, without a shell to run it
+    module Paths
+      # A directory the hook guessed because the shell decides the real one when it runs
+      # (`cd "$REPO"`): the hook's cwd, or a path relative to it. A snapshot there may not cover
+      # the repository the command changes, and the hook says so.
+      class Guessed < String; end
+
+      module_function
+
+      # The directory after `cd PATH` or `git -C PATH` from dir. A path the shell decides falls
+      # back to `fallback` (the directory Claude runs in) as a Guessed directory, and a relative
+      # path from a guessed directory stays guessed.
+      def change_dir(path, dir, fallback)
+        return Guessed.new(fallback) if unresolved?(path)
+
+        resolved = expand(path, dir)
+        dir.is_a?(Guessed) && !absolute?(path) ? Guessed.new(resolved) : resolved
+      end
+
+      def guessed?(dir)
+        dir.is_a?(Guessed)
+      end
+
+      def absolute?(path)
+        path.start_with?('/')
+      end
+
+      # File.expand_path, except that `~user` for an unknown user is kept as a literal name
+      # instead of raising: an error here must not stop the hook from deciding
+      def expand(path, dir)
+        File.expand_path(path, dir)
+      rescue ArgumentError
+        File.join(File.expand_path(dir), path)
+      end
+
+      # Whether the shell decides the path when it runs: a variable, a command substitution or
+      # `cd -`. The text alone does not say which directory that is.
+      def unresolved?(path)
+        path == '-' || path.match?(/[$`]/)
+      end
+    end
+  end
+end

data/lib/gitflash/hook/rules.rb

@@ -7,10 +7,15 @@ module Gitflash
     # { scope:, branches:, dir: } where branches may contain :current for the checked-out one.
     module Rules
       FULL = %w[branches head worktree].freeze
+      # A command too deeply nested to read (see CommandParser#nested): save everything
+      UNREAD = :unread
 
       module_function
 
       def for(subcommand, args, dir)
+        # No branch names: the snapshot keeps every branch
+        return { scope: FULL } if subcommand == UNREAD
+
         rule = RULES[subcommand]
         rule&.call(args, dir)
       end
@@ -34,16 +39,27 @@ module Gitflash
 
       def path_arg?(args, dir)
         args.reject { |arg| arg.start_with?('-') }.any? do |arg|
-          File.exist?(File.expand_path(arg, dir))
+          File.exist?(Paths.expand(arg, dir))
         end
       end
 
-      def clean(args, _dir)
+      # `git clean` without -f removes files too when clean.requireForce is false
+      def clean(args, dir)
         flags = args.select { |arg| arg.start_with?('-') }
         short = short_flags(args)
-        removes = any?(flags, %w[--force --interactive]) || short.match?(/[fi]/)
+        removes = any?(flags, %w[--force --interactive]) || short.match?(/[fi]/) ||
+                  !require_force?(dir)
         dry_run = flags.include?('--dry-run') || short.include?('n')
-        removes && !dry_run ? { scope: %w[worktree] } : nil
+        return nil unless removes && !dry_run
+
+        # -x and -X delete ignored files too
+        { scope: %w[worktree], ignored: short.match?(/[xX]/) }
+      end
+
+      def require_force?(dir)
+        stdout, _stderr, success = Git::BashCommand.capture('git', '-C', dir, 'config', '--bool',
+                                                            'clean.requireForce')
+        !(success && stdout.strip == 'false')
       end
 
       def switch(args, _dir)
@@ -63,10 +79,15 @@ module Gitflash
                   short_flags(args).match?(/[dDfmMcC]/)
         return nil unless changes
 
-        { scope: %w[branches], branches: args.reject { |arg| arg.start_with?('-') } }
+        names = args.reject { |arg| arg.start_with?('-') }
+        # A name the shell or xargs fills in (`$b`, `{}`) is unknown: save every branch
+        names = [] if names.any? { |name| Paths.unresolved?(name) || name.include?('{}') }
+        { scope: %w[branches], branches: names }
       end
 
       def update_ref(args, _dir)
+        # `--stdin` reads the refs to delete from input the text does not show: save all branches
+        return { scope: %w[branches] } if args.include?('--stdin')
         return nil unless args.include?('-d')
 
         heads = args.select { |arg| arg.start_with?('refs/heads/') }
@@ -81,12 +102,13 @@ module Gitflash
         any?(args, %w[--abort --quit]) ? { scope: %w[worktree] } : nil
       end
 
-      # `git worktree remove --force PATH` deletes that worktree's uncommitted files
+      # `git worktree remove PATH` deletes that worktree's ignored files, and with --force its
+      # uncommitted ones too
       def worktree(args, dir)
-        return nil unless args.first == 'remove' && any?(args, %w[-f --force])
+        return nil unless args.first == 'remove'
 
         path = args[1..].reject { |arg| arg.start_with?('-') }.first
-        path && { scope: %w[worktree], dir: File.expand_path(path, dir) }
+        path && { scope: %w[worktree], dir: Paths.change_dir(path, dir, dir), ignored: true }
       end
 
       RULES = {
@@ -104,7 +126,7 @@ module Gitflash
         'revert' => method(:abort),
         'am' => method(:abort),
         'worktree' => method(:worktree)
-      }.freeze
+      }.merge(HistoryRules::RULES).freeze
     end
   end
 end

data/lib/gitflash/hook/settings.rb

@@ -44,16 +44,33 @@ module Gitflash
       def read(path)
         return {} unless File.exist?(path)
 
-        JSON.parse(File.read(path))
+        check_shape!(path, JSON.parse(File.read(path)))
       rescue JSON::ParserError => e
         raise Error.new("#{path} is not valid JSON: #{e.message}", code: 'invalid_settings')
+      rescue SystemCallError => e
+        raise Error.new("#{path} cannot be read: #{e.message}", code: 'invalid_settings')
+      end
+
+      def check_shape!(path, data)
+        # A missing `hooks` key is a file without hooks yet; a present one must be an object
+        # whose events are lists of objects, as Claude Code reads them
+        return data if data.is_a?(Hash) && (!data.key?('hooks') || hooks_shape?(data['hooks']))
+
+        raise Error.new("#{path} does not hold a JSON object whose `hooks` maps each event to " \
+                        'a list of objects', code: 'invalid_settings')
+      end
+
+      def hooks_shape?(hooks)
+        hooks.is_a?(Hash) &&
+          hooks.values.all? { |groups| groups.is_a?(Array) && groups.all?(Hash) }
       end
 
       # The gitflash hook entry for an event (PreToolUse by default) in parsed settings, or nil.
       # Only groups whose matcher covers the Bash tool count: a gitflash command under another
       # matcher (Edit, say) never runs for Bash commands.
       def entry(settings, event = 'PreToolUse')
-        groups = Array(settings.dig('hooks', event))
+        hooks = settings['hooks']
+        groups = hooks.is_a?(Hash) ? Array(hooks[event]) : []
         bash = groups.select { |group| bash_matcher?(group['matcher']) }
         bash.flat_map { |group| Array(group['hooks']) }
             .find { |hook| hook['command'].to_s.match?(PATTERN) }

data/lib/gitflash/hook/shell_quotes.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Hook
+    # Where quoted text and substitutions end in a shell command line (see ShellText)
+    module ShellQuotes
+      module_function
+
+      # The first backtick at or after index that no backslash escapes, or the end of the line
+      def closing_backtick(line, index)
+        while index < line.length
+          return index if line[index] == '`'
+
+          index += line[index] == '\\' ? 2 : 1
+        end
+        line.length
+      end
+
+      # The `)` that closes a parenthesis opened before index, skipping quoted text and nested
+      # substitutions and subshells, or the end of the line
+      def closing_paren(line, index)
+        while index < line.length
+          return index if line[index] == ')'
+
+          index = after_in_parens(line, index)
+        end
+        line.length
+      end
+
+      def after_in_parens(line, index)
+        case line[index]
+        when '\\' then index + 2
+        when "'" then closing_single(line, index + 1) + 1
+        when '"' then closing_double(line, index + 1) + 1
+        when '`' then closing_backtick(line, index + 1) + 1
+        when '(' then closing_paren(line, index + 1) + 1
+        else index + 1
+        end
+      end
+
+      def closing_single(line, index)
+        line.index("'", index) || line.length
+      end
+
+      # The `"` that closes a double-quoted string opened before index
+      def closing_double(line, index)
+        while index < line.length
+          return index if line[index] == '"'
+
+          index = after_in_double(line, index)
+        end
+        line.length
+      end
+
+      def after_in_double(line, index)
+        return index + 2 if line[index] == '\\'
+        return closing_backtick(line, index + 1) + 1 if line[index] == '`'
+        return closing_paren(line, index + 2) + 1 if line[index, 2] == '$('
+
+        index + 1
+      end
+    end
+  end
+end