gitflash 0.7.0.beta1 → 0.7.0.beta3

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)
-        force = flags.include?('--force') || short.include?('f')
-        dry_run = any?(flags, %w[--dry-run --interactive]) || short.match?(/[ni]/)
-        force && !dry_run ? { scope: %w[worktree] } : nil
+        removes = any?(flags, %w[--force --interactive]) || short.match?(/[fi]/) ||
+                  !require_force?(dir)
+        dry_run = flags.include?('--dry-run') || short.include?('n')
+        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)
@@ -59,12 +75,19 @@ module Gitflash
       end
 
       def branch(args, _dir)
-        return nil unless any?(args, %w[-d -D --delete -f --force -m -M --move -C --copy])
-
-        { scope: %w[branches], branches: args.reject { |arg| arg.start_with?('-') } }
+        changes = any?(args, %w[--delete --force --move --copy]) ||
+                  short_flags(args).match?(/[dDfmMcC]/)
+        return nil unless changes
+
+        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/') }
@@ -79,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 = {
@@ -102,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

data/lib/gitflash/hook/shell_text.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Hook
+    # Reads a shell command line as text, without running it: where commands end, and which
+    # commands run inside `$(...)`, `<(...)` and backticks. Quotes are followed as the shell
+    # does: nothing runs inside single quotes, `$(...)` and backticks run inside double quotes,
+    # and a backslash keeps the next character (outside single quotes).
+    module ShellText
+      SEPARATORS = ";&|\n"
+
+      module_function
+
+      # The command line split on ; & | and newlines outside quotes and substitutions
+      def segments(line)
+        scan(line).first
+      end
+
+      # The scripts the shell runs to build the line: the text inside `$(...)`, `<(...)`,
+      # `>(...)` and backticks. Nested ones are found when the caller reads each script in turn.
+      def substitutions(line)
+        scan(line).last
+      end
+
+      # [segments, scripts] in one pass over the line
+      def scan(line)
+        parts = [+'']
+        scripts = []
+        index = 0
+        quote = nil
+        index, quote = step(line, index, quote, parts, scripts) while index < line.length
+        [parts.reject { |part| part.strip.empty? }, scripts]
+      end
+
+      # Reads what starts at index and returns where to go on, with the quote then open
+      def step(line, index, quote, parts, scripts)
+        char = line[index]
+        return [index + 1, close_single(char, parts)] if quote == "'"
+        return take(line, index, index + 2, parts) + [quote] if char == '\\'
+        return [comment_end(line, index), nil] if quote.nil? && comment?(line, index)
+
+        substituted(line, index, quote, parts, scripts) || plain(char, index, quote, parts)
+      end
+
+      # Takes a substitution that opens at index, or returns nil
+      def substituted(line, index, quote, parts, scripts)
+        script = substitution(line, index, quote)
+        return nil unless script
+
+        scripts << line[script.first...script.last]
+        take(line, index, script.last + 1, parts) + [quote]
+      end
+
+      # A `#` that starts a word outside quotes starts a comment, which runs to the end of the
+      # line; an apostrophe in it (`# don't`) must not open a quote
+      def comment?(line, index)
+        line[index] == '#' && (index.zero? || line[index - 1].match?(/[\s;&|()]/))
+      end
+
+      def comment_end(line, index)
+        line.index("\n", index) || line.length
+      end
+
+      def close_single(char, parts)
+        parts.last << char
+        char == "'" ? nil : "'"
+      end
+
+      def plain(char, index, quote, parts)
+        if !quote && SEPARATORS.include?(char)
+          parts << +''
+          return [index + 1, nil]
+        end
+        parts.last << char
+        [index + 1, next_quote(char, quote)]
+      end
+
+      def next_quote(char, quote)
+        return (char == '"' ? nil : quote) if quote
+        return char if ["'", '"'].include?(char)
+
+        nil
+      end
+
+      def take(line, from, to, parts)
+        parts.last << line[from...to].to_s
+        [to]
+      end
+
+      # [script start, closing index] of a substitution opening at index, or nil. `<(...)` and
+      # `>(...)` only open outside quotes; `$(...)` and backticks also inside double quotes.
+      def substitution(line, index, quote)
+        if line[index] == '`'
+          [index + 1, ShellQuotes.closing_backtick(line, index + 1)]
+        elsif line[index, 2] == '$(' || (quote.nil? && line[index, 2].match?(/\A[<>]\(/))
+          [index + 2, ShellQuotes.closing_paren(line, index + 2)]
+        end
+      end
+    end
+  end
+end

data/lib/gitflash/hook/wrappers.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Hook
+    # Commands that run the command after them: `sudo -u me git ...`, `timeout 5 git ...`,
+    # `xargs git ...`. Strips them, with their options, so the parser sees the git command.
+    module Wrappers
+      # Wrapper => its options that take a value as the next word
+      OPTIONS = {
+        'sudo' => %w[-u -g -h -p -C -D -r -t -U -T --user --group --host --prompt --chdir],
+        'env' => %w[-u -C -S --unset --chdir --split-string],
+        'command' => [], 'exec' => %w[-a], 'time' => %w[-f -o --format --output],
+        'nohup' => [], 'nice' => %w[-n --adjustment], 'ionice' => %w[-c -n -p -P -u],
+        'stdbuf' => %w[-i -o -e], 'chronic' => [], 'caffeinate' => %w[-t -w],
+        'timeout' => %w[-k -s --kill-after --signal],
+        # -i, -l and -e take only an attached value (`-i{}`), so they are not listed
+        'xargs' => %w[-I -n -P -L -d -E -s -a --arg-file --delimiter --max-args --max-procs]
+      }.freeze
+      # Wrappers whose first word after the options is not the command (`timeout 5 git ...`)
+      LEADING_ARGUMENT = %w[timeout].freeze
+      CHDIR_OPTIONS = %w[-C -D --chdir].freeze
+      FIND_EXEC = %w[-exec -execdir -ok -okdir].freeze
+      FIND_END = [';', '\;', '+'].freeze
+
+      module_function
+
+      # The words without leading wrappers and their options, and the directory `sudo -D` or
+      # `env -C` switch to (nil when none does)
+      def strip(words)
+        chdir = nil
+        while (options = OPTIONS[File.basename(words.first.to_s)])
+          name = File.basename(words.first)
+          words, dir = drop_options(words.drop(1), options)
+          chdir = dir || chdir
+          words = words.drop(1) if LEADING_ARGUMENT.include?(name)
+        end
+        [words, chdir]
+      end
+
+      # Drops options (and the values of those that take one) up to the command
+      def drop_options(words, with_value)
+        chdir = nil
+        while (word = words.first)&.start_with?('-')
+          words = words.drop(1)
+          break if word == '--'
+          next unless with_value.include?(word)
+
+          chdir = words.first if CHDIR_OPTIONS.include?(word)
+          words = words.drop(1)
+        end
+        [words, chdir]
+      end
+
+      # The command `find ... -exec CMD ... ;` runs, or nil
+      def find_exec(words)
+        return nil unless File.basename(words.first.to_s) == 'find'
+
+        start = words.index { |word| FIND_EXEC.include?(word) }
+        return nil unless start
+
+        command = words[(start + 1)..].take_while { |word| !FIND_END.include?(word) }
+                                      .reject { |word| word == '{}' }
+        command.empty? ? nil : command
+      end
+    end
+  end
+end

data/lib/gitflash/hook_cli.rb

@@ -14,8 +14,12 @@ module Gitflash
       true
     end
 
+    TERMINAL_NOTE = 'gitflash hook claude is run by Claude Code, not by hand. Use ' \
+                    '`gitflash hook install` to set it up and `gitflash hook status` to check it.'
+
     desc 'claude',
-         'Run as a Claude Code hook (PreToolUse and PostToolUse; reads the input on stdin)'
+         'Run as a Claude Code hook (PreToolUse and PostToolUse; reads the input on stdin)',
+         hide: true
     long_desc <<~TEXT
       Reads the Claude Code hook input on stdin. When the Bash command can discard work git
       cannot restore (for example reset --hard, clean -f, checkout -- ., branch -D, stash drop),
@@ -29,14 +33,33 @@ module Gitflash
       branch NAME, worktree add) as agent work, so `gitflash clean --agent` can find them. A branch
       is only marked when it is new (its reflog says it was created a moment ago) and unmarked.
 
-      Errors never block the command: they are printed to stderr and the hook exits with 0.
+      Not meant to be run by hand: in a terminal it only prints a note. Errors are printed to
+      stderr and the hook exits with 0. In snapshot mode the command then runs; in ask mode the
+      user is asked and in deny mode the command is blocked, so an error never turns the
+      protection off. If even that answer cannot be written, ask and deny mode exit with 2,
+      which makes Claude Code block the command.
     TEXT
     option :mode, type: :string, default: 'snapshot', enum: Hook::Claude::MODES
     def claude
-      output = Hook::Claude.new(mode: options[:mode]).call($stdin.read)
+      return puts(TERMINAL_NOTE) if $stdin.tty?
+
+      output = hook_output(options[:mode], $stdin.read)
       puts JSON.generate(output) if output
     rescue StandardError => e
       warn "gitflash hook: #{e.message}"
+      # No decision could be written: exit 2 makes Claude Code block the command in ask and
+      # deny mode instead of running it unprotected
+      exit 2 unless options[:mode] == 'snapshot'
+    end
+
+    no_commands do
+      # The hook's output; on an error, what Hook::Failure decides for the mode
+      def hook_output(mode, input)
+        Hook::Claude.new(mode: mode).call(input)
+      rescue StandardError => e
+        warn "gitflash hook: #{e.message}"
+        Hook::Failure.output(mode, e, input)
+      end
     end
 
     desc 'install', 'Register the gitflash hook in Claude Code settings'
@@ -52,13 +75,20 @@ module Gitflash
                        applies to sessions started there
       --scope user     ~/.claude/settings.json; applies to every session
 
+      --mode snapshot|ask|deny sets what the hook does (see `gitflash hook help claude`). Without
+      --mode an installed hook keeps its mode. A mode that protects less than the installed one
+      (deny, then ask, then snapshot) is refused unless you pass --downgrade.
+
       Claude Code reloads settings files, so running sessions pick the hook up without a restart.
       Check the result with `gitflash hook status`.
 
       Accepts the global --json and --dry-run options after the subcommand: gitflash hook install --json
     TEXT
     option :scope, type: :string, default: 'local', enum: Commands::HookInstall::SCOPES
-    option :mode, type: :string, default: 'snapshot', enum: Hook::Claude::MODES
+    option :mode, type: :string, enum: Hook::Claude::MODES,
+                  desc: 'snapshot, ask or deny (default: the installed mode, else snapshot)'
+    option :downgrade, type: :boolean,
+                       desc: 'Allow a --mode that protects less than the installed one'
     def install
       run_command('hook install', Commands::HookInstall, repo_required: options[:scope] != 'user')
     end

data/lib/gitflash/protection.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
 module Gitflash
-  # Branches gitflash never deletes: the current and default branch, `main`, `master`, names
-  # matching `protected` in the settings, and any branch checked out in a worktree.
+  # Branches gitflash never deletes: the current and default branch, the usual long-lived
+  # branches (`main`, `master`, `develop`, `development`, `trunk`, `release/*`), names matching
+  # `protected` in the settings, and any branch checked out in a worktree. The long-lived names
+  # count even when the default branch is something else or unknown: in a git-flow repository
+  # `develop` is merged into `main` after every release and would otherwise look done.
   class Protection
-    NAMES = %w[main master].freeze
+    NAMES = %w[main master develop development trunk].freeze
+    PATTERNS = %w[release/*].freeze
 
     def initialize(config:, checked_out: [])
       @config = config
@@ -12,8 +16,12 @@ module Gitflash
     end
 
     def protected?(branch)
-      branch.current? || branch.default? || NAMES.include?(branch.name) ||
+      branch.current? || branch.default? || long_lived?(branch.name) ||
         @config.protected?(branch.name) || @checked_out.include?(branch.name)
     end
+
+    def long_lived?(name)
+      NAMES.include?(name) || PATTERNS.any? { |pattern| File.fnmatch?(pattern, name) }
+    end
   end
 end

data/lib/gitflash/repo.rb

@@ -39,12 +39,13 @@ module Gitflash
     end
 
     def toplevel
-      @bash.exec('git', 'rev-parse', '--show-toplevel').strip
+      @bash.exec('git', 'rev-parse', '--show-toplevel').delete_suffix("\n")
     end
 
     # Root of the main checkout; differs from toplevel inside a linked worktree
     def main_root
-      common = @bash.exec('git', 'rev-parse', '--path-format=absolute', '--git-common-dir').strip
+      common = @bash.exec('git', 'rev-parse', '--path-format=absolute',
+                          '--git-common-dir').delete_suffix("\n")
       File.basename(common) == '.git' ? File.dirname(common) : toplevel
     end
 

data/lib/gitflash/snapshot.rb

@@ -12,9 +12,10 @@ module Gitflash
   # worktree       commit whose tree is the working tree including untracked files (not
   #                ignored ones), nil when the tree was clean
   # skipped_files  untracked files left out because they were too large
+  # excluded_files untracked files left out because `snapshot_exclude` matches them
   Snapshot = Data.define(
     :id, :created_at, :reason, :scope, :worktree_path, :head, :branches, :stashes,
-    :index, :worktree, :skipped_files
+    :index, :worktree, :skipped_files, :excluded_files
   ) do
     def self.from_h(hash)
       new(
@@ -22,10 +23,16 @@ module Gitflash
         scope: hash['scope'], worktree_path: hash['worktree_path'],
         head: { branch: hash.dig('head', 'branch'), sha: hash.dig('head', 'sha') },
         branches: hash['branches'] || {}, stashes: hash['stashes'] || [],
-        index: hash['index'], worktree: hash['worktree'], skipped_files: hash['skipped_files'] || []
+        index: hash['index'], worktree: hash['worktree'],
+        skipped_files: hash['skipped_files'] || [], excluded_files: hash['excluded_files'] || []
       )
     end
 
+    # Untracked files this snapshot cannot bring back
+    def unsaved_files
+      skipped_files + excluded_files
+    end
+
     def scope?(part)
       scope.include?(part)
     end

data/lib/gitflash/snapshot_check.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Gitflash
+  # Checks a snapshot read from a ref before gitflash trusts it. Anyone with write access to the
+  # repository can create such a ref, and its fields go into git commands and paths.
+  module SnapshotCheck
+    SHA = /\A\h{40}(?:\h{24})?\z/
+    # What git accepts in a branch name, roughly: no control characters, spaces, `~^:?*[\`, `..`
+    # or `@{`, no leading `-` or `/`, no `//`, no trailing `/`, `.` or `.lock`
+    BRANCH = %r{\A(?!-|/)(?!.*(?:\.\.|@\{|//))[^\x00-\x20\x7F~^:?*\[\\]+(?<![/.])(?<!\.lock)\z}
+
+    module_function
+
+    # Why the snapshot read from ref cannot be trusted, or nil
+    def problem(ref, snapshot)
+      shape_problem(snapshot) || field_problem(ref, snapshot)
+    end
+
+    # Fields of the wrong type, which the other checks could not even read
+    def shape_problem(snapshot)
+      return 'branches is not an object' unless snapshot.branches.is_a?(Hash)
+      return 'stashes is not a list' unless snapshot.stashes.is_a?(Array)
+      return 'scope is not a list of names' unless snapshot.scope.is_a?(Array) &&
+                                                   snapshot.scope.all?(String)
+
+      nil
+    end
+
+    def field_problem(ref, snapshot)
+      expected = Snapshots::REF_PREFIX + snapshot.id.to_s
+      return 'its name does not match its id' unless ref == expected
+      return 'a commit id is not a full hex SHA' unless snapshot.object_ids.all? { |id| sha?(id) }
+      return 'a branch name is not valid' unless branch_names(snapshot).all? { |n| branch?(n) }
+      return 'worktree_path is not an absolute path' unless path?(snapshot.worktree_path)
+
+      nil
+    end
+
+    # BRANCH, and each slash-separated part non-empty, not starting with `.` and not ending in
+    # `.lock`; `@` alone is not a branch name either
+    def branch?(name)
+      name.match?(BRANCH) && name != '@' && name.split('/', -1).all? do |part|
+        !part.empty? && !part.start_with?('.') && !part.end_with?('.lock')
+      end
+    end
+
+    def sha?(id)
+      id.is_a?(String) && id.match?(SHA)
+    end
+
+    def branch_names(snapshot)
+      (snapshot.branches.keys + [snapshot.head[:branch]]).compact.map(&:to_s)
+    end
+
+    # nil for snapshots from before worktree_path was recorded
+    def path?(path)
+      path.nil? || (path.is_a?(String) && path.start_with?('/') && !path.match?(/[\x00-\x1F]/))
+    end
+  end
+end

data/lib/gitflash/snapshots.rb

@@ -31,11 +31,34 @@ module Gitflash
       store(Snapshot.new(**identity, reason: reason, **state))
     end
 
-    # Snapshots, newest first
+    # Snapshots, newest first. A ref whose message is not a snapshot is skipped with a warning,
+    # so one damaged ref cannot stop every command that lists or takes snapshots.
+    # Ordered by the time inside each snapshot, not by ref name, so a ref named to sort first
+    # cannot become the default for `undo`.
     def list
-      git('for-each-ref', '--sort=-refname', '--format=%(contents:subject)', REF_PREFIX)
+      git('for-each-ref', '--format=%(refname)%00%(contents:subject)', REF_PREFIX)
         .each_line(chomp: true).reject(&:empty?)
-        .map { |line| Snapshot.from_h(JSON.parse(line)) }
+        .filter_map { |line| parse(*line.split("\0", 2)) }
+        .sort_by { |snapshot| [Time.iso8601(snapshot.created_at), snapshot.id] }.reverse
+    end
+
+    def parse(ref, message)
+      data = JSON.parse(message.to_s)
+      raise TypeError, 'not an object' unless data.is_a?(Hash)
+
+      checked(ref, Snapshot.from_h(data))
+    rescue JSON::ParserError, TypeError, ArgumentError => e
+      warn "gitflash: skipping #{TerminalText.line(ref)}, which is not a readable snapshot " \
+           "(#{e.message.lines.first&.strip})"
+      nil
+    end
+
+    def checked(ref, snapshot)
+      Time.iso8601(snapshot.created_at.to_s)
+      problem = SnapshotCheck.problem(ref, snapshot)
+      raise TypeError, problem if problem
+
+      snapshot
     end
 
     def find(id)