gitflash 0.7.0.beta1 → 0.7.0.beta3

data/lib/gitflash/hook/command_parser.rb

@@ -1,7 +1,5 @@
 # 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:
@@ -13,14 +11,42 @@ module Gitflash
     # `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)
+      # dir: where to take the snapshot; branches: names, or :current for the checked-out one;
+      # guessed: the shell decides the directory (`cd "$REPO"`), so dir is only a fallback;
+      # ignored: whether the command also deletes ignored files, which no snapshot saves
+      Target = Data.define(:dir, :command, :scope, :branches, :guessed, :ignored) do
+        # One target for all the commands of a group that run in dir
+        def self.merge(dir, group)
+          new(dir: dir, command: group.map(&:command).join(' && '),
+              scope: group.flat_map(&:scope).uniq, branches: merged_branches(group),
+              guessed: group.any?(&:guessed), ignored: group.any?(&:ignored))
+        end
+
+        # A target that saves branches without naming them saves every branch, so the merge
+        # does too: naming the others' branches would drop the ones it could not name
+        def self.merged_branches(group)
+          all = group.any? { |target| target.scope.include?('branches') && target.branches.empty? }
+          all ? [] : group.flat_map(&:branches).uniq
+        end
+      end
 
-      PREFIXES = %w[sudo command exec time nohup env].freeze
-      OPTIONS_WITH_VALUE = %w[-c --git-dir --work-tree --namespace --exec-path --config-env].freeze
+      SHELLS = %w[bash sh zsh dash ksh].freeze
+      MAX_NESTING = 3
+      # Subcommands git never lets an alias replace and that have no rule, so their aliases need
+      # not be read
+      BUILTINS = (Rules::RULES.keys + %w[status log diff show add commit push pull fetch rev-parse
+                                         config ls-files remote describe blame grep tag init
+                                         clone mv]).freeze
 
-      def initialize(cwd)
+      DIR_COMMANDS = %w[cd pushd popd].freeze
+
+      # `aliases` returns the git aliases configured for a directory, as { name => value }
+      def initialize(cwd, aliases: GitInvocation.method(:configured_aliases))
         @cwd = cwd
+        @aliases = aliases
+        @alias_cache = {}
+        @invocation = GitInvocation.new(dir_after: method(:change_dir),
+                                        aliases: method(:aliases_in))
       end
 
       # Git commands that can lose work, with what to save before them
@@ -29,8 +55,10 @@ module Gitflash
           rule = Rules.for(git.subcommand, git.args, git.dir)
           next unless rule
 
-          Target.new(dir: rule.fetch(:dir, git.dir), command: git.command, scope: rule[:scope],
-                     branches: rule[:branches] || [])
+          dir = rule.fetch(:dir, git.dir)
+          Target.new(dir: dir.to_s, command: git.command, scope: rule[:scope],
+                     branches: rule[:branches] || [], guessed: Paths.guessed?(dir),
+                     ignored: rule.fetch(:ignored, false))
         end
       end
 
@@ -48,73 +76,86 @@ module Gitflash
       # subcommand and its arguments
       GitCommand = Data.define(:dir, :command, :subcommand, :args)
 
-      def git_commands(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
+      def git_commands(command_line, dir = @cwd, depth = 0)
+        stack = []
+        ShellText.segments(command_line).flat_map do |segment|
+          words = CommandWords.new(segment)
+          if DIR_COMMANDS.include?(words.words.first)
+            dir = dir_after(words.words, dir, stack)
+            next substituted(segment, dir, depth)
           end
-          git_command(words, dir, segment.strip) if File.basename(words.first) == 'git'
+          substituted(segment, dir, depth) + in_segment(words, dir, segment.strip, depth)
         end
       end
 
-      # 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
+      # `cd DIR` and `pushd DIR` move, `pushd` remembering where it was; `popd` goes back there,
+      # or to the directory Claude runs in when the line pushed nothing
+      def dir_after(words, dir, stack)
+        return stack.pop || @cwd if words.first == 'popd'
+
+        stack.push(dir) if words.first == 'pushd'
+        change_dir(words[1] || Dir.home, dir)
+      end
+
+      def in_segment(words, dir, segment, depth)
+        return [] if words.words.empty?
+
+        dir = change_dir(words.chdir, dir) if words.chdir
+        commands_in(words.words, dir, segment, depth, words.env)
+      end
+
+      # Git commands inside `$(...)`, `<(...)` and backticks, which the shell runs first
+      def substituted(command_line, dir, depth)
+        ShellText.substitutions(command_line).flat_map do |script|
+          nested(script, dir, depth)
         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
+      # The git commands of a script inside this one. Past the nesting limit a script that
+      # mentions git counts as risky without being read, so deep nesting cannot hide a command.
+      def nested(script, dir, depth)
+        return git_commands(script, dir, depth + 1) if depth < MAX_NESTING
+        return [] unless script.match?(/\bgit\b/)
+
+        [GitCommand.new(dir: dir, command: script.strip, subcommand: Rules::UNREAD, args: [])]
       end
 
-      def prefix?(word)
-        PREFIXES.include?(word) || word.match?(/\A\w+=/)
+      # The git command of one segment, or the ones inside `bash -c "..."`, `eval "..."`,
+      # `find -exec` and `!` aliases
+      def commands_in(words, dir, segment, depth, env = {})
+        words = Wrappers.find_exec(words) || words
+        git = File.basename(words.first.to_s) == 'git'
+        return git_command(words, dir, segment, depth, env) if git
+
+        script = nested_script(words)
+        script ? nested(script, dir, depth) : []
       end
 
-      def split(segment)
-        Shellwords.split(segment)
-      rescue ArgumentError
-        segment.split
+      # The script text passed to a shell (`bash -c`, `sh -lc`) or to `eval`
+      def nested_script(words)
+        return words.drop(1).join(' ') if words.first == 'eval'
+        return nil unless SHELLS.include?(File.basename(words.first))
+
+        index = words.index { |word| word.match?(/\A-[a-z]*c[a-z]*\z/) }
+        index && words[index + 1]
       end
 
-      def unwrap(word)
-        word.delete_prefix('(').delete_prefix('{').delete_suffix(')').delete_suffix('}')
+      # The directory after `cd PATH` or `git -C PATH`. A path the shell decides when it runs
+      # (`cd "$(git rev-parse --show-toplevel)"`, `cd "$REPO"`, `cd -`) falls back to the
+      # directory Claude runs in: a snapshot there is better than none.
+      def change_dir(path, dir)
+        Paths.change_dir(path, dir, @cwd)
       end
 
-      def git_command(words, dir, command)
-        index, dir = skip_git_options(words, dir)
-        GitCommand.new(dir: dir, command: command, subcommand: words[index],
-                       args: words[(index + 1)..] || [])
+      def git_command(words, dir, command, depth, env)
+        git = @invocation.parse(words, dir, env)
+        return nested(git.script, git.dir, depth) if git.script
+
+        [GitCommand.new(dir: git.dir, command: command, subcommand: git.subcommand, args: git.args)]
       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]
+      def aliases_in(dir)
+        @alias_cache[dir] ||= @aliases.call(dir)
       end
     end
   end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Hook
+    # What the PreToolUse hook tells Claude about a risky command
+    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, " \
+          "restore it with #{undo_commands(saved)} (list snapshots with `gitflash snapshots`)."
+      end
+
+      # One command per snapshot: with several directories each snapshot belongs to its own
+      def undo_commands(saved)
+        return "`gitflash undo #{saved.first[1].id}`" if saved.size == 1
+
+        saved.map { |target, snap| "`gitflash undo #{snap.id}` (run in #{target.dir})" }.join(', ')
+      end
+
+      def unsaved(targets)
+        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)
+        "gitflash blocked #{commands(targets)}: 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.'
+      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
+    end
+  end
+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