gitflash 0.7.0.beta1 → 0.7.0.beta3

data/lib/gitflash/config.rb

@@ -4,29 +4,52 @@ require 'yaml'
 
 module Gitflash
   # Settings from `.gitflash.yml` in the main checkout and `~/.config/gitflash.yml`.
-  # Precedence: repository file, then user file, then built-in defaults.
+  # Precedence: repository file, then user file, then built-in defaults; for `worktree_dir` the
+  # user file wins, since it decides where on the user's disk checkouts are written.
   # Command-line flags are applied by the commands themselves and win over all of these.
   # An unknown key or a value of the wrong type raises a UsageError, so a typo never goes unnoticed.
-  Config = Data.define(:protected_patterns, :stale_days, :worktree_dir) do
-    # `root` is the main checkout; `home` is where the user file lives
+  Config = Data.define(:protected_patterns, :stale_days, :worktree_dir, :worktree_dir_from_repo,
+                       :snapshot_exclude) do
+    # `root` is the main checkout; `home` is where the user file lives. The repository file wins
+    # key by key, except `protected`: both files add patterns, so a repository can protect more
+    # branches but never remove what the user protects; and `worktree_dir`, where the user file
+    # wins. A cloned repository's file may only place worktrees next to the main checkout.
     def self.load(root:, home: Dir.home)
-      values = [File.join(home, ConfigKeys::USER_FILE), File.join(root, ConfigKeys::REPO_FILE)]
-               .map { |path| read(path) }
-               .reduce(ConfigKeys::DEFAULTS) { |merged, layer| merged.merge(layer) }
-      new(protected_patterns: values['protected'], stale_days: values['stale_days'],
-          worktree_dir: values['worktree_dir'])
+      user = read(File.join(home, ConfigKeys::USER_FILE))
+      repo = read(File.join(root, ConfigKeys::REPO_FILE), repository: true)
+      values = ConfigKeys::DEFAULTS.merge(user).merge(repo)
+      new(protected_patterns: both([user, repo], 'protected'), stale_days: values['stale_days'],
+          snapshot_exclude: both([user, repo], 'snapshot_exclude'), **worktree_dir_of(user, repo))
     end
 
+    # Lists that both files add to
+    def self.both(layers, key)
+      layers.flat_map { |layer| layer.fetch(key, []) }.uniq
+    end
+    private_class_method :both
+
+    # The user file wins for worktree_dir; a value from the repository is checked again where
+    # it leads (see ConfigKeys.check_contained!)
+    def self.worktree_dir_of(user, repo)
+      from_repo = !user.key?('worktree_dir') && repo.key?('worktree_dir')
+      dir = from_repo ? repo['worktree_dir'] : user.fetch('worktree_dir', ConfigKeys::DEFAULT_WORKTREE_DIR)
+      { worktree_dir: dir,
+        worktree_dir_from_repo: from_repo }
+    end
+    private_class_method :worktree_dir_of
+
     def self.defaults
-      new(protected_patterns: [], stale_days: 30, worktree_dir: ConfigKeys::DEFAULT_WORKTREE_DIR)
+      new(protected_patterns: [], stale_days: 30, worktree_dir: ConfigKeys::DEFAULT_WORKTREE_DIR,
+          worktree_dir_from_repo: false, snapshot_exclude: [])
     end
 
-    def self.read(path)
+    def self.read(path, repository: false)
       return {} unless File.file?(path)
 
       reject_duplicate_keys!(path)
       data = YAML.safe_load_file(path) || {}
       validate!(data, path)
+      check_repository_dir!(data['worktree_dir'], path) if repository
       data
     rescue Psych::Exception, SystemCallError, IOError => e
       raise invalid(path, "cannot be read (#{e.message.lines.first.strip})")
@@ -75,21 +98,51 @@ module Gitflash
     end
     private_class_method :check_types!
 
+    # A repository's file comes with the clone, so its worktree_dir must stay next to the main
+    # checkout: relative, no `~`, and not climbing above the main checkout's parent
+    def self.check_repository_dir!(template, path)
+      return if template.nil? || ConfigKeys.contained?(template)
+
+      raise invalid(path, "'worktree_dir' must be a relative path that stays next to the " \
+                          'repository (set other places in ~/.config/gitflash.yml)')
+    end
+    private_class_method :check_repository_dir!
+
     def self.invalid(path, problem)
       UsageError.new("#{path} #{problem}", code: 'invalid_config')
     end
     private_class_method :invalid
 
-    # True when the branch name matches a configured pattern (shell-style `*` and `?`)
+    # True when the branch name matches a configured pattern (shell-style `*`, `?`, `[abc]` and
+    # `{a,b}`)
     def protected?(name)
-      protected_patterns.any? { |pattern| File.fnmatch?(pattern, name) }
+      protected_patterns.any? { |pattern| File.fnmatch?(pattern, name, File::FNM_EXTGLOB) }
+    end
+
+    # True when an untracked file must stay out of snapshots: the pattern matches its path or
+    # its name (`*.pem`, `.env*`, `secrets/*`)
+    def snapshot_excluded?(path)
+      flags = File::FNM_PATHNAME | File::FNM_DOTMATCH
+      names = excluded_candidates(path)
+      snapshot_exclude.any? { |pattern| names.any? { |name| File.fnmatch?(pattern, name, flags) } }
+    end
+
+    # The path, its name, and every directory above it: a pattern that matches a directory
+    # (`secrets`, `secrets/*`) covers everything below it, as in .gitignore
+    def excluded_candidates(path)
+      parts = path.split('/')
+      dirs = (1...parts.size).map { |count| parts.first(count).join('/') }
+      [path, File.basename(path), *dirs]
     end
 
-    # Directory for a new worktree. `%{repo}` and `%{branch}` are replaced; a relative path
-    # is resolved against the main checkout. Slashes in a branch name stay as folders.
+    # Directory for a new worktree. `%<repo>s` and `%<branch>s` are replaced as plain text; a
+    # relative path is resolved against the main checkout. Slashes in a branch name stay as
+    # folders.
     def worktree_path(root:, branch:)
-      path = format(worktree_dir, repo: File.basename(root), branch: branch)
-      File.expand_path(path, root)
+      path = worktree_dir.gsub('%<repo>s') { File.basename(root) }.gsub('%<branch>s') { branch }
+      path = File.expand_path(path, root)
+      ConfigKeys.check_contained!(path, root) if worktree_dir_from_repo
+      path
     end
   end
 end

data/lib/gitflash/config_keys.rb

@@ -7,13 +7,73 @@ module Gitflash
     USER_FILE = File.join('.config', 'gitflash.yml')
     DEFAULT_WORKTREE_DIR = '../%<repo>s.worktrees/%<branch>s'
     DEFAULTS = {
-      'protected' => [], 'stale_days' => 30, 'worktree_dir' => DEFAULT_WORKTREE_DIR
+      'protected' => [], 'stale_days' => 30, 'worktree_dir' => DEFAULT_WORKTREE_DIR,
+      'snapshot_exclude' => []
     }.freeze
+    PLACEHOLDERS = ['%<repo>s', '%<branch>s'].freeze
+    MAX_TEMPLATE_LENGTH = 512
     CHECKS = {
-      'protected' => [->(v) { v.is_a?(Array) && v.all?(String) },
-                      'a list of branch name patterns'],
+      'protected' => [->(v) { v.is_a?(Array) && v.all? { |pattern| branch_pattern?(pattern) } },
+                      'a list of branch name patterns (no spaces, control characters, ~, ^ or :)'],
       'stale_days' => [->(v) { v.is_a?(Integer) && v.positive? }, 'a positive whole number'],
-      'worktree_dir' => [->(v) { v.is_a?(String) && !v.empty? }, 'a non-empty string']
+      'worktree_dir' => [->(v) { template?(v) },
+                         'a path of up to 512 characters that uses only %<repo>s and %<branch>s'],
+      'snapshot_exclude' => [->(v) { v.is_a?(Array) && v.all?(String) },
+                             'a list of file name patterns']
     }.freeze
+
+    # Whether a template resolves inside the parent of the main checkout, for any repository and
+    # branch name (branch names cannot hold `..`)
+    def self.contained?(template)
+      return false if template.start_with?('/', '~')
+
+      root = '/parent/repo'
+      path = template.gsub('%<repo>s', 'repo').gsub('%<branch>s', 'branch')
+      File.expand_path(path, root).start_with?("#{File.dirname(root)}/")
+    end
+
+    # A pattern that can match a branch name: characters git refuses in branch names, such as a
+    # space at either end, would make it match nothing without any warning
+    def self.branch_pattern?(value)
+      return false unless value.is_a?(String) && !value.empty?
+      return false if value.match?(/[\x00-\x20\x7F~^:\\]/)
+
+      # `..` is never in a branch name; inside `{..,a}` it is only one of the alternatives
+      alternatives(value).any? { |pattern| !pattern.include?('..') }
+    end
+
+    # The patterns `{a,b}` stands for, innermost braces first, as File::FNM_EXTGLOB reads them
+    def self.alternatives(pattern)
+      match = pattern.match(/\{([^{}]*)\}/)
+      return [pattern] unless match
+
+      match[1].split(',', -1).flat_map do |choice|
+        alternatives(match.pre_match + choice + match.post_match)
+      end
+    end
+
+    # A path template: the two placeholders are the only `%` directives, so a width such as
+    # `%<repo>999999999s` can never make Ruby build a huge string
+    def self.template?(value)
+      return false unless value.is_a?(String)
+      return false if value.empty? || value.length > MAX_TEMPLATE_LENGTH
+
+      !PLACEHOLDERS.reduce(value) { |rest, placeholder| rest.gsub(placeholder, '') }.include?('%')
+    end
+
+    # A repository's worktree_dir passed a check on the text alone; a symbolic link in the
+    # repository (`wt-link -> /elsewhere`) could still lead out, so the real location of the
+    # deepest existing directory on the way must stay next to the main checkout too
+    def self.check_contained!(path, root)
+      parent = File.realpath(File.dirname(root))
+      existing = path
+      existing = File.dirname(existing) until File.exist?(existing)
+      real = File.join(File.realpath(existing), path.delete_prefix(existing))
+      return if real.start_with?("#{parent}/")
+
+      raise UsageError.new("worktree_dir in #{REPO_FILE} leads to #{real}, outside " \
+                           "#{parent}; set worktree_dir in ~/.config/gitflash.yml to use it",
+                           code: 'invalid_config')
+    end
   end
 end

data/lib/gitflash/confirmation_required.rb

@@ -2,10 +2,14 @@
 
 module Gitflash
   # Raised when a destructive command runs without a terminal and without --yes.
-  # Carries the plan so the caller can review it and re-run with --yes.
+  # Carries the plan so the caller can review it and re-run with --yes, or, for a change
+  # gitflash undo cannot revert, the token to pass to --confirm.
   class ConfirmationRequired < Error
-    def initialize(message = nil, plan: nil)
+    attr_reader :confirm_token
+
+    def initialize(message = nil, plan: nil, confirm_token: nil)
       super(message, code: 'confirmation_required', plan: plan)
+      @confirm_token = confirm_token
     end
 
     def exit_code

data/lib/gitflash/git/bash_command.rb

@@ -16,9 +16,12 @@ module Gitflash
         end
 
         # Runs a command without a shell and returns [stdout, stderr, success].
-        # `env` adds environment variables for this command only.
+        # `env` adds environment variables for this command only. The executable is passed as a
+        # pair, which keeps Ruby from handing a lone string to a shell.
         def capture(*args, env: {})
-          stdout, stderr, status = Open3.capture3(env, *args)
+          raise CommandError, 'no command given' if args.empty?
+
+          stdout, stderr, status = Open3.capture3(env, [args.first, args.first], *args.drop(1))
           [stdout, stderr, status.success?]
         rescue SystemCallError => e
           raise CommandError, "#{args.join(' ')} failed: #{e.message}"

data/lib/gitflash/hook/branch_marker.rb

@@ -1,30 +1,133 @@
 # frozen_string_literal: true
 
+require 'digest'
+require 'fileutils'
+require 'json'
+require 'tmpdir'
+
 module Gitflash
   module Hook
     # Marks the branches an agent just created as agent work (see Ownership), so
     # `gitflash clean --agent` can find them. Runs in the PostToolUse hook, after the command:
     # the branch exists then, and Claude Code only runs it when the command succeeded.
     #
-    # A branch is marked only when it is unmarked and its reflog says it was created a moment
-    # ago ("branch: Created from ..."), so a branch that was already there is never claimed.
+    # Text in a command proves nothing (`false && git branch x` creates nothing), so a branch is
+    # only marked when it is new:
+    # - the PreToolUse hook records which of the branches the command names exist before it runs
+    #   (`record`), and a branch that existed then is never marked;
+    # - its reflog must say it was created a moment ago ("branch: Created from ..."), which also
+    #   covers a Claude Code that ran no PreToolUse hook;
+    # - it must be unmarked.
     class BranchMarker
       CREATED = 'branch: Created from'
       RECENT_SECONDS = 120
+      STALE_RECORD_SECONDS = 24 * 60 * 60
 
-      def initialize(clock: -> { Time.now })
+      def initialize(clock: -> { Time.now }, state_dir: nil)
         @clock = clock
+        @state_dir = state_dir || File.join(Dir.tmpdir, "gitflash-hook-#{Process.uid}")
+      end
+
+      # PreToolUse: remember the branches the command may create that exist already
+      def record(command, cwd, tool_use_id)
+        creations = CommandParser.new(cwd).creations(command)
+        return if creations.empty? || (path = record_path(tool_use_id)).nil?
+        return unless private_state_dir?
+
+        prune_records
+        File.write(path, JSON.generate(existing_stamps(creations)))
       end
 
-      # Branch names marked as agent work, in the directories the command ran in
-      def call(command, cwd)
+      # PostToolUse: branch names marked as agent work, in the directories the command ran in
+      def call(command, cwd, tool_use_id = nil)
+        existed = take_record(tool_use_id)
         created = CommandParser.new(cwd).creations(command)
-        created.select { |creation| mark(creation[:dir], creation[:branch]) }
+        created.reject { |creation| already_there?(existed, creation) }
+               .select { |creation| mark(creation[:dir], creation[:branch]) }
                .map { |creation| creation[:branch] }.uniq
       end
 
       private
 
+      # { key => stamp } of the named branches that exist now
+      def existing_stamps(creations)
+        existing = creations.select { |creation| branch_exists?(creation[:dir], creation[:branch]) }
+        existing.to_h { |creation| [key(creation), stamp(creation)] }
+      end
+
+      def key(creation)
+        "#{creation[:dir]}\0#{creation[:branch]}"
+      end
+
+      # A branch that was there before the command and is the same branch now. One that the
+      # command deleted and created again has a new reflog, so a new stamp, and counts as new.
+      # An empty stamp (no reflog) is no evidence of a new branch either: all that is known is
+      # that the branch existed, and claiming a branch a person may have made is the worse
+      # mistake, so it is left alone. Without a reflog nothing could be marked in any case.
+      def already_there?(existed, creation)
+        existed.key?(key(creation)) && existed[key(creation)] == stamp(creation)
+      end
+
+      # Time, commit and message of the oldest reflog entry, which is the creation of the branch;
+      # empty when the reflog is off
+      def stamp(creation)
+        return '' unless Dir.exist?(creation[:dir])
+
+        stdout, _stderr, success = Git::BashCommand.capture(
+          'git', '-C', creation[:dir], 'log', '-g', '--format=%ct %H %gs',
+          "#{Repo::HEADS}#{creation[:branch]}", '--'
+        )
+        success ? stdout.lines(chomp: true).last.to_s : ''
+      end
+
+      # One file per tool call, named from a hash so the id can never form a path
+      def record_path(tool_use_id)
+        return nil if tool_use_id.to_s.empty?
+
+        File.join(@state_dir, "#{Digest::SHA256.hexdigest(tool_use_id.to_s)}.json")
+      end
+
+      def take_record(tool_use_id)
+        path = record_path(tool_use_id)
+        return {} unless path && private_state_dir? && File.file?(path)
+
+        record = JSON.parse(File.read(path))
+        record.is_a?(Hash) ? record : {}
+      rescue JSON::ParserError
+        {}
+      ensure
+        FileUtils.rm_f(path) if path
+      end
+
+      # The directory holds the records of this user only: created with mode 0700, and refused
+      # when it is a link, belongs to someone else or is open to the group or others (a shared
+      # /tmp lets another user create the name first)
+      def private_state_dir?
+        FileUtils.mkdir_p(@state_dir, mode: 0o700)
+        stat = File.lstat(@state_dir)
+        stat.directory? && stat.owned? && stat.mode.nobits?(0o077)
+      rescue SystemCallError
+        false
+      end
+
+      # Another hook may delete a record at the same moment: a vanished file is not an error
+      def prune_records
+        Dir.glob(File.join(@state_dir, '*.json')).each do |file|
+          FileUtils.rm_f(file) if @clock.call - File.mtime(file) > STALE_RECORD_SECONDS
+        rescue SystemCallError
+          next
+        end
+      end
+
+      def branch_exists?(dir, branch)
+        return false unless Dir.exist?(dir)
+
+        _stdout, _stderr, success = Git::BashCommand.capture(
+          'git', '-C', dir, 'show-ref', '--verify', '--quiet', "#{Repo::HEADS}#{branch}"
+        )
+        success
+      end
+
       def mark(dir, branch)
         return false unless Dir.exist?(dir)
 

data/lib/gitflash/hook/claude.rb

@@ -29,21 +29,39 @@ module Gitflash
         data = JSON.parse(input)
         return after_command(data) if data['hook_event_name'] == POST_EVENT
 
+        before_command(data)
+      end
+
+      private
+
+      # PreToolUse: remember which branches exist, then snapshot, ask or deny for risky commands
+      def before_command(data)
+        record_branches(data)
         targets = targets(data)
         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)
+        merged = merge_by_dir(targets)
+        saved = merged.filter_map { |target| save(target) }
+        # Asking is the user's protection: it must not depend on a snapshot having been saved.
+        # A command that runs where nothing could be saved is always reported to the agent.
+        output(saved, merged - saved.map(&:first))
       end
 
-      private
+      # Recording is a side feature: when it fails, snapshots and the ask or deny decision still run
+      def record_branches(data)
+        return unless bash?(data)
+
+        @marker.record(command_of(data), data['cwd'] || Dir.pwd, data['tool_use_id'])
+      rescue StandardError => e
+        warn "gitflash hook: could not record branches (#{e.message})"
+      end
 
       # PostToolUse: mark the branches the command created, and tell Claude
       def after_command(data)
         return nil unless data['tool_name'] == 'Bash'
 
-        marked = @marker.call(data.dig('tool_input', 'command').to_s, data['cwd'] || Dir.pwd)
+        marked = @marker.call(command_of(data), data['cwd'] || Dir.pwd, data['tool_use_id'])
         return nil if marked.empty?
 
         context = "gitflash marked #{marked.join(', ')} as agent work, so " \
@@ -52,24 +70,27 @@ module Gitflash
         { hookSpecificOutput: { hookEventName: POST_EVENT, additionalContext: context } }
       end
 
+      def bash?(data)
+        data['tool_name'] == 'Bash'
+      end
+
+      def command_of(data)
+        data.dig('tool_input', 'command').to_s
+      end
+
       def targets(data)
-        return [] unless data['tool_name'] == 'Bash'
+        return [] unless bash?(data)
 
-        command = data.dig('tool_input', 'command').to_s
-        CommandParser.new(data['cwd'] || Dir.pwd).targets(command)
+        CommandParser.new(data['cwd'] || Dir.pwd).targets(command_of(data))
       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
+        targets.group_by(&:dir).map { |dir, group| CommandParser::Target.merge(dir, group) }
       end
 
-      # [target, snapshot], or nil when the directory is not a git work tree
+      # [target, snapshot], or nil when the directory is not a git work tree or saving failed.
+      # A failure must not stop the ask decision, so it is warned about here and not raised.
       def save(target)
         return nil unless Dir.exist?(target.dir)
 
@@ -80,6 +101,9 @@ module Gitflash
                                             scope: target.scope, branches: branches(target))
           [target, snapshot]
         end
+      rescue StandardError => e
+        warn "gitflash hook: could not save a snapshot in #{target.dir} (#{e.message})"
+        nil
       end
 
       # Full ref shortened by removing refs/heads/ only; `--short` changes when a tag has the name
@@ -87,17 +111,18 @@ module Gitflash
         git('symbolic-ref', '--quiet', 'HEAD')&.delete_prefix(Repo::HEADS)
       end
 
+      # The branches to save; nil (all of them) when the command does not name its branches, as
+      # in `xargs git branch -D < list`
       def branches(target)
+        return nil if target.branches.empty?
+
         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`).'
+      def output(saved, unsaved)
+        context = Messages.context(saved, unsaved)
         specific = { hookEventName: EVENT, additionalContext: context }
         if @mode == 'ask'
           specific[:permissionDecision] = 'ask'
@@ -108,12 +133,8 @@ module Gitflash
       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 } }
+                                permissionDecisionReason: Messages.denial(targets) } }
       end
 
       # Stripped stdout of a git command, or nil when it fails