gitflash 0.5.1 → 0.7.0.beta1

data/lib/gitflash/commands/worktree_prune.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Commands
+    # Forgets worktrees whose directory is gone (locked ones stay). Branches are not touched.
+    # Takes no snapshot: only git's own bookkeeping for the missing directory is removed.
+    class WorktreePrune < WorktreeCommand
+      def call
+        stale = worktrees.list.select { |worktree| worktree.missing? && !worktree.locked? }
+        return noop if stale.empty?
+
+        prune_or_ask({ worktrees: stale.map(&:path) })
+      end
+
+      private
+
+      def prune_or_ask(plan)
+        return planned(plan, "Would prune:\n#{bullets(plan)}") if ui.dry_run?
+
+        question = "You are about to prune:\n\n#{bullets(plan)}"
+        ui.confirm?(question, plan: plan) ? prune(plan) : cancelled(plan)
+      end
+
+      def prune(plan)
+        result = worktrees.prune
+        git_error!('worktree prune', result) unless result.success?
+
+        ui.report(status: 'done', plan: plan, result: { pruned: plan[:worktrees] },
+                  text: "Pruned:\n#{bullets(plan)}")
+      end
+
+      def noop
+        ui.report(status: 'noop', result: { pruned: [] }, text: 'No missing worktrees to prune')
+      end
+
+      def bullets(plan)
+        plan[:worktrees].map { |path| "* #{path}" }.join("\n")
+      end
+    end
+  end
+end

data/lib/gitflash/commands/worktree_remove.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Commands
+    # Removes worktrees given as paths or branch names, or picked from a menu.
+    # The main checkout, the worktree gitflash runs in, locked and dirty worktrees are refused
+    # unless --force is given (the main checkout and the current one never can be removed).
+    # Each removal saves a snapshot of the worktree first; `gitflash undo ID` brings the
+    # directory, its branch and its uncommitted files back.
+    class WorktreeRemove < WorktreeCommand
+      include RemovalReport
+
+      def call(*targets)
+        worktrees = Worktrees.new(repo: repo).list
+        targets = pick(worktrees) if targets.empty?
+        return 0 if targets.nil?
+
+        chosen = resolve(targets, worktrees)
+        remove(chosen)
+      end
+
+      private
+
+      def pick(worktrees)
+        require_interactive!('Pass the worktrees to remove: gitflash wt remove PATH_OR_BRANCH...')
+        choices = worktrees.reject { |worktree| worktree.main? || current?(worktree) }
+                           .to_h { |wt| ["#{wt.branch || '(detached)'}  #{wt.path}", wt.path] }
+        return report_nothing('No worktrees available to remove') if choices.empty?
+
+        picked = ui.multi_select('Select worktrees to remove', choices)
+        picked.empty? ? report_nothing('No worktrees selected') : picked
+      end
+
+      def force?
+        options[:force] ? true : false
+      end
+
+      def current?(worktree)
+        worktree.path == repo.toplevel
+      end
+
+      def resolve(targets, worktrees)
+        chosen = targets.uniq.map { |target| find!(target, worktrees) }.uniq(&:path)
+        refused = chosen.filter_map do |worktree|
+          worktree.removal_blocker(force: force?, current: current?(worktree))
+        end
+        usage_error!('protected_worktree', refused.join('; ')) if refused.any?
+        chosen
+      end
+
+      def remove(chosen)
+        plan = build_plan(chosen)
+        return planned(plan, "Would remove:\n#{preview(chosen, plan)}") if dry_run?
+        return cancelled(plan) unless ui.confirm?(summary(chosen, plan), plan: plan)
+
+        outcomes = chosen.map { |worktree| remove_one(worktree) }
+        report_results(plan, outcomes)
+      end
+
+      def dry_run? = ui.dry_run?
+
+      def preview(chosen, plan) = "#{bullets(chosen)}#{ignored_warning(plan)}"
+
+      # The plan reported and returned in JSON; `wt clean` adds why each worktree was chosen
+      def build_plan(chosen)
+        { worktrees: chosen.map { |worktree| plan_row(worktree) }, force: force? }
+      end
+
+      def plan_row(worktree)
+        ignored = worktree.missing? ? [] : Worktrees.new(repo: repo).ignored(worktree.path)
+        { path: worktree.path, branch: worktree.branch, dirty: worktree.dirty?,
+          locked: worktree.locked?, ignored_count: ignored.size, ignored: ignored.first(5) }
+      end
+
+      def remove_one(worktree)
+        snapshot = snapshot_for(worktree)
+        unsaved = snapshot.skipped_files
+        return refuse_unsaved(worktree, unsaved) if unsaved.any?
+
+        result = Worktrees.new(repo: repo).remove(worktree.path, force: force?)
+        Removal.new(worktree: worktree, result: result, snapshot: (snapshot if result.success?))
+      end
+
+      # Files a snapshot cannot hold (untracked and over 50 MB) would be lost for good
+      def refuse_unsaved(worktree, files)
+        shown = files.first(3).join(', ')
+        shown += ", and #{files.size - 3} more" if files.size > 3
+        message = "#{files.size} untracked file(s) over 50 MB cannot be saved by a snapshot " \
+                  "(#{shown}); move or delete them first"
+        Removal.new(worktree: worktree, result: Result.new(success: false, output: message),
+                    snapshot: nil)
+      end
+
+      # A missing directory has no HEAD or files to save; only the branch tip is
+      def snapshot_for(worktree)
+        reason = "gitflash wt remove #{worktree.path}"
+        branches = [worktree.branch].compact
+        return take_snapshot(reason, scope: %w[branches], branches: branches) if worktree.missing?
+
+        take_snapshot(reason, scope: %w[branches head worktree], branches: branches,
+                              dir: worktree.path)
+      end
+
+      def summary(chosen, plan)
+        "You are about to remove the following worktrees:\n\n#{bullets(chosen)}" \
+          "#{ignored_warning(plan)}"
+      end
+
+      def bullets(chosen)
+        chosen.map { |worktree| "* #{worktree.path} (#{worktree.branch || 'detached'})" }.join("\n")
+      end
+
+      def report_nothing(text)
+        ui.report(status: 'noop', result: { removed: [], failed: [] }, text: text)
+        nil
+      end
+    end
+  end
+end

data/lib/gitflash/commands/worktree_unlock.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Commands
+    # Unlocks a worktree; see WorktreeLock
+    class WorktreeUnlock < WorktreeLock
+      private
+
+      def lock? = false
+    end
+  end
+end

data/lib/gitflash/config.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+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.
+  # 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
+    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'])
+    end
+
+    def self.defaults
+      new(protected_patterns: [], stale_days: 30, worktree_dir: ConfigKeys::DEFAULT_WORKTREE_DIR)
+    end
+
+    def self.read(path)
+      return {} unless File.file?(path)
+
+      reject_duplicate_keys!(path)
+      data = YAML.safe_load_file(path) || {}
+      validate!(data, path)
+      data
+    rescue Psych::Exception, SystemCallError, IOError => e
+      raise invalid(path, "cannot be read (#{e.message.lines.first.strip})")
+    end
+    private_class_method :read
+
+    # A YAML loader keeps only the last of two equal keys, which could drop a `protected` list
+    def self.reject_duplicate_keys!(path)
+      root = Psych.parse_file(path)
+      return unless root
+
+      duplicate = duplicate_key(root)
+      raise invalid(path, "has the key '#{duplicate}' more than once") if duplicate
+    end
+    private_class_method :reject_duplicate_keys!
+
+    def self.duplicate_key(node)
+      own = node.is_a?(Psych::Nodes::Mapping) ? own_duplicate(node) : nil
+      own || (node.children || []).filter_map { |child| duplicate_key(child) }.first
+    end
+    private_class_method :duplicate_key
+
+    def self.own_duplicate(mapping)
+      keys = mapping.children.each_slice(2).filter_map do |key, _value|
+        key.value if key.respond_to?(:value)
+      end
+      keys.tally.find { |_key, count| count > 1 }&.first
+    end
+    private_class_method :own_duplicate
+
+    def self.validate!(data, path)
+      raise invalid(path, 'must be a mapping') unless data.is_a?(Hash)
+
+      unknown = data.keys - ConfigKeys::DEFAULTS.keys
+      raise invalid(path, "has unknown keys: #{unknown.join(', ')}") if unknown.any?
+
+      check_types!(data, path)
+    end
+    private_class_method :validate!
+
+    def self.check_types!(data, path)
+      data.each do |key, value|
+        check, expected = ConfigKeys::CHECKS.fetch(key)
+        raise invalid(path, "'#{key}' must be #{expected}") unless check.call(value)
+      end
+    end
+    private_class_method :check_types!
+
+    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 `?`)
+    def protected?(name)
+      protected_patterns.any? { |pattern| File.fnmatch?(pattern, name) }
+    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.
+    def worktree_path(root:, branch:)
+      path = format(worktree_dir, repo: File.basename(root), branch: branch)
+      File.expand_path(path, root)
+    end
+  end
+end

data/lib/gitflash/config_keys.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Gitflash
+  # Built-in defaults, files and the check each key must pass
+  module ConfigKeys
+    REPO_FILE = '.gitflash.yml'
+    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
+    }.freeze
+    CHECKS = {
+      'protected' => [->(v) { v.is_a?(Array) && v.all?(String) },
+                      'a list of branch name patterns'],
+      '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']
+    }.freeze
+  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/git/in_directory.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Git
+    # Runs every git command inside another directory (`git -C DIR ...`). It has the same
+    # interface as BashCommand, so StateCapture, Snapshots and Restore can work on a linked
+    # worktree without knowing about it.
+    class InDirectory
+      def initialize(path, bash: BashCommand)
+        @path = path
+        @bash = bash
+      end
+
+      def exec(*args, env: {})
+        @bash.exec(*scoped(args), env: env)
+      end
+
+      def capture(*args, env: {})
+        @bash.capture(*scoped(args), env: env)
+      end
+
+      private
+
+      def scoped(args)
+        args.first == 'git' ? ['git', '-C', @path, *args.drop(1)] : args
+      end
+    end
+  end
+end

data/lib/gitflash/hook/branch_marker.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+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.
+    class BranchMarker
+      CREATED = 'branch: Created from'
+      RECENT_SECONDS = 120
+
+      def initialize(clock: -> { Time.now })
+        @clock = clock
+      end
+
+      # Branch names marked as agent work, in the directories the command ran in
+      def call(command, cwd)
+        created = CommandParser.new(cwd).creations(command)
+        created.select { |creation| mark(creation[:dir], creation[:branch]) }
+               .map { |creation| creation[:branch] }.uniq
+      end
+
+      private
+
+      def mark(dir, branch)
+        return false unless Dir.exist?(dir)
+
+        Dir.chdir(dir) do
+          ownership = Ownership.new
+          next false unless created_recently?(branch) && !ownership.all.key?(branch)
+
+          ownership.mark(branch, 'agent')
+          true
+        end
+      end
+
+      # The oldest reflog entry of the branch is its creation, and it is recent
+      def created_recently?(branch)
+        stdout, _stderr, success = Git::BashCommand.capture(
+          'git', 'log', '-g', '--format=%ct%x1f%gs', "#{Repo::HEADS}#{branch}", '--'
+        )
+        return false unless success
+
+        created, subject = stdout.lines(chomp: true).last.to_s.split("\x1f", 2)
+        subject.to_s.start_with?(CREATED) && @clock.call.to_i - created.to_i <= RECENT_SECONDS
+      end
+    end
+  end
+end

data/lib/gitflash/hook/claude.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Gitflash
+  module Hook
+    # Claude Code hook for the Bash tool. PostToolUse input marks the branches the command
+    # created as agent work (BranchMarker); everything below describes PreToolUse.
+    #
+    # 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'
+      POST_EVENT = 'PostToolUse'
+
+      def initialize(mode: 'snapshot', snapshots: -> { Gitflash::Snapshots.new },
+                     marker: BranchMarker.new)
+        @mode = mode
+        @snapshots = snapshots
+        @marker = marker
+      end
+
+      def call(input)
+        data = JSON.parse(input)
+        return after_command(data) if data['hook_event_name'] == POST_EVENT
+
+        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)
+      end
+
+      private
+
+      # 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)
+        return nil if marked.empty?
+
+        context = "gitflash marked #{marked.join(', ')} as agent work, so " \
+                  '`gitflash clean --agent` can find it. Change it with ' \
+                  '`gitflash mark BRANCH --owner human`.'
+        { hookSpecificOutput: { hookEventName: POST_EVENT, additionalContext: context } }
+      end
+
+      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,121 @@
+# 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
+
+      # Git commands that can lose work, with what to save before them
+      def targets(command_line)
+        git_commands(command_line).filter_map do |git|
+          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] || [])
+        end
+      end
+
+      # Branches that git commands in the line create, as { dir:, branch: }
+      def creations(command_line)
+        git_commands(command_line).filter_map do |git|
+          branch = Creations.for(git.subcommand, git.args)
+          { dir: git.dir, branch: branch } if branch
+        end
+      end
+
+      private
+
+      # A git command found in the line: the directory it runs in (after `cd` and `-C`), the
+      # 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
+          end
+          git_command(words, dir, segment.strip) if File.basename(words.first) == 'git'
+        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
+        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_command(words, dir, command)
+        index, dir = skip_git_options(words, dir)
+        GitCommand.new(dir: dir, command: command, subcommand: words[index],
+                       args: words[(index + 1)..] || [])
+      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