gitflash 0.4.0 → 0.5.0

data/lib/gitflash/commands/reset.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Commands
+    # Resets the current branch to a commit given as an argument or picked from a menu.
+    # Default mode is mixed; --soft and --hard are supported. Only --hard asks for confirmation.
+    # The result includes the previous HEAD, so the reset can be reverted.
+    class Reset < Base
+      HARD_RESET_WARNING = 'You are about to reset your branch and lose all your current changes'
+
+      def call(ref = nil)
+        mode = reset_mode
+
+        if ref.nil?
+          require_interactive!('Pass the commit to reset to: gitflash reset COMMIT')
+          commits = repo.commits
+          return report_single_commit if commits.size < 2
+
+          ref = ui.select('Select a commit to reset to', commits.to_h { |c| [c.label, c.sha] })
+        end
+
+        reset(ref, mode)
+      end
+
+      private
+
+      def reset_mode
+        if options[:soft] && options[:hard]
+          usage_error!('invalid_options', 'Use either --soft or --hard, not both')
+        end
+
+        return 'hard' if options[:hard]
+
+        options[:soft] ? 'soft' : 'mixed'
+      end
+
+      def reset(ref, mode)
+        commit = repo.resolve_commit(ref)
+        usage_error!('unknown_commit', "Unknown commit '#{ref}'") if commit.nil?
+
+        plan = { commit: commit, mode: mode }
+        text = "reset to #{commit[0, 7]} (#{mode})"
+        return planned(plan, "Would #{text}") if ui.dry_run?
+        return cancelled(plan) unless confirmed?(plan)
+
+        execute(plan, text)
+      end
+
+      def execute(plan, text)
+        previous = repo.resolve_commit('HEAD')
+        result = repo.reset(plan[:commit], mode: plan[:mode])
+        git_error!('reset', result) unless result.success?
+
+        ui.report(status: 'done', plan: plan, result: plan.merge(previous_commit: previous),
+                  text: text.capitalize)
+      end
+
+      def confirmed?(plan)
+        plan[:mode] != 'hard' || ui.confirm?(HARD_RESET_WARNING, plan: plan)
+      end
+
+      def report_single_commit
+        ui.report(status: 'noop', result: nil, text: 'You only have one commit!')
+      end
+    end
+  end
+end

data/lib/gitflash/commit.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Gitflash
+  # A commit as reported by `git log`
+  Commit = Data.define(:sha, :subject, :author, :committed_at) do
+    # Parses one line produced with Repo::COMMIT_FORMAT
+    def self.parse(line)
+      sha, subject, author, date = line.split(Repo::SEPARATOR, 4)
+      new(sha: sha, subject: subject.to_s, author: author, committed_at: Time.iso8601(date))
+    end
+
+    def label
+      "#{sha} - #{subject}"
+    end
+
+    def to_h
+      super.merge(committed_at: committed_at.iso8601)
+    end
+  end
+end

data/lib/gitflash/confirmation_required.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+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.
+  class ConfirmationRequired < Error
+    def initialize(message = nil, plan: nil)
+      super(message, code: 'confirmation_required', plan: plan)
+    end
+
+    def exit_code
+      2
+    end
+
+    def status
+      'confirmation_required'
+    end
+  end
+end

data/lib/gitflash/error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Gitflash
+  # Base class for errors reported to the user.
+  # `code` is a stable machine-readable identifier; `plan` is the planned change, if any.
+  class Error < StandardError
+    attr_reader :code, :plan
+
+    def initialize(message = nil, code: 'failed', plan: nil)
+      super(message)
+      @code = code
+      @plan = plan
+    end
+
+    def exit_code
+      1
+    end
+
+    def status
+      'error'
+    end
+  end
+end

data/lib/gitflash/git/bash_command.rb

@@ -9,16 +9,18 @@ module Gitflash
         # 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, status = Open3.capture3(*args)
-          raise CommandError, "#{args.join(' ')} failed: #{stderr.strip}" unless status.success?
+          stdout, stderr, success = capture(*args)
+          raise CommandError, "#{args.join(' ')} failed: #{stderr.strip}" unless success
 
           stdout
-        rescue SystemCallError => e
-          raise CommandError, "#{args.join(' ')} failed: #{e.message}"
         end
 
-        def system_exec(*)
-          system(*)
+        # Runs a command without a shell and returns [stdout, stderr, success].
+        def capture(*args)
+          stdout, stderr, status = Open3.capture3(*args)
+          [stdout, stderr, status.success?]
+        rescue SystemCallError => e
+          raise CommandError, "#{args.join(' ')} failed: #{e.message}"
         end
       end
     end

data/lib/gitflash/git/command_error.rb

@@ -2,6 +2,10 @@
 
 module Gitflash
   module Git
-    class CommandError < StandardError; end
+    class CommandError < Gitflash::Error
+      def initialize(message = nil, code: 'git_failed', plan: nil)
+        super
+      end
+    end
   end
 end

data/lib/gitflash/repo.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Gitflash
+  # Reads and changes the git repository in the current working directory.
+  # All git access goes through this class; it never prompts or prints.
+  class Repo
+    SEPARATOR = "\x1f"
+    BRANCH_FORMAT = %w[
+      refname:short objectname:short HEAD upstream:short upstream:track,nobracket
+      committerdate:iso-strict authorname subject
+    ].map { |field| "%(#{field})" }.join('%1f')
+    COMMIT_FORMAT = %w[%h %s %an %cI].join('%x1f')
+    COMMITS_LIMIT = 100
+    FALLBACK_DEFAULT_BRANCHES = %w[main master].freeze
+
+    def initialize(bash: Git::BashCommand)
+      @bash = bash
+    end
+
+    def ensure_work_tree!
+      inside = @bash.exec('git', 'rev-parse', '--is-inside-work-tree').strip == 'true'
+      raise Error.new('Not a git repository', code: 'not_a_repository') unless inside
+    rescue Git::CommandError
+      raise Error.new('Not a git repository', code: 'not_a_repository')
+    end
+
+    # Local branches. With `merged_status: true` each branch also reports whether it is
+    # merged into the default branch (one extra git call).
+    def branches(merged_status: false)
+      merged_names = merged_status ? merged_branch_names : nil
+      branch_lines.map do |line|
+        Branch.parse(line, default_branch: default_branch, merged_names: merged_names)
+      end
+    end
+
+    def current_branch
+      branches.find(&:current?)&.name
+    end
+
+    # The branch that origin/HEAD points to, else main or master when present locally
+    def default_branch
+      return @default_branch if defined?(@default_branch)
+
+      @default_branch = default_ref&.delete_prefix('origin/')
+    end
+
+    # Commits of the current branch, newest first. Empty for a branch without commits.
+    def commits(limit: COMMITS_LIMIT)
+      @bash.exec('git', 'log', "--max-count=#{limit}", "--format=#{COMMIT_FORMAT}")
+           .each_line(chomp: true).reject(&:empty?).map { |line| Commit.parse(line) }
+    rescue Git::CommandError
+      []
+    end
+
+    # Full sha of a commit reference, or nil when it does not name a commit
+    def resolve_commit(ref)
+      stdout, _stderr, success = @bash.capture('git', 'rev-parse', '--verify', '--quiet',
+                                               "#{ref}^{commit}")
+      success ? stdout.strip : nil
+    end
+
+    def checkout(branch)
+      run('git', 'checkout', branch, '--')
+    end
+
+    def delete_branch(branch, force: false)
+      run('git', 'branch', force ? '-D' : '-d', branch)
+    end
+
+    def reset(commit, mode:)
+      run('git', 'reset', "--#{mode}", commit, '--')
+    end
+
+    private
+
+    def branch_lines
+      @branch_lines ||= @bash.exec('git', 'for-each-ref', "--format=#{BRANCH_FORMAT}",
+                                   'refs/heads/')
+                             .each_line(chomp: true).reject(&:empty?)
+    end
+
+    # Ref used to check merge status: origin/HEAD's target, else a local main/master
+    def default_ref
+      return @default_ref if defined?(@default_ref)
+
+      @default_ref = remote_default_ref || local_default_branch
+    end
+
+    def remote_default_ref
+      ref = @bash.exec('git', 'symbolic-ref', '--quiet', '--short',
+                       'refs/remotes/origin/HEAD').strip
+      ref.empty? ? nil : ref
+    rescue Git::CommandError
+      nil
+    end
+
+    def local_default_branch
+      names = branch_lines.map { |line| line.split(SEPARATOR, 2).first }
+      FALLBACK_DEFAULT_BRANCHES.find { |name| names.include?(name) }
+    end
+
+    def merged_branch_names
+      return nil unless default_ref
+
+      @bash.exec('git', 'for-each-ref', "--merged=#{default_ref}", '--format=%(refname:short)',
+                 'refs/heads/')
+           .each_line(chomp: true).to_set
+    end
+
+    def run(*)
+      stdout, stderr, success = @bash.capture(*)
+      Result.new(success: success,
+                 output: [stdout, stderr].map(&:strip).reject(&:empty?).join("\n"))
+    end
+  end
+end

data/lib/gitflash/result.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Gitflash
+  # Outcome of a git command that changes the repository
+  Result = Data.define(:success, :output) do
+    alias_method :success?, :success
+  end
+end

data/lib/gitflash/ui.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Gitflash
+  # Everything the user sees: human text or JSON, menus and confirmations.
+  # Menus and confirmations are only shown in a terminal and never in JSON mode.
+  #
+  # JSON output always uses the same envelope (see schema/v1.json):
+  #   { schema, command, ok, status, dry_run, plan?, result?, error? }
+  class Ui
+    JSON_SCHEMA_VERSION = 1
+    OK_STATUSES = %w[done planned noop cancelled].freeze
+
+    def initialize(command:, json: false, yes: false, dry_run: false)
+      @command = command
+      @json = json
+      @yes = yes
+      @dry_run = dry_run
+    end
+
+    def json?
+      @json
+    end
+
+    def dry_run?
+      @dry_run
+    end
+
+    def interactive?
+      !json? && $stdin.tty?
+    end
+
+    # Reports the outcome of a command and returns its exit status.
+    # `status` is one of done, planned, noop, cancelled or failed.
+    def report(status:, text:, plan: nil, result: nil, error: nil)
+      if json?
+        document = envelope(status: status, plan: plan, result: result, error: error)
+        $stdout.puts JSON.generate(document)
+      else
+        $stdout.puts text
+      end
+      OK_STATUSES.include?(status) ? 0 : 1
+    end
+
+    def error(error)
+      if json?
+        details = { code: error.code, message: error.message, exit_code: error.exit_code }
+        $stdout.puts JSON.generate(envelope(status: error.status, plan: error.plan, error: details))
+      else
+        warn error.message
+      end
+    end
+
+    def select(message, choices, **)
+      prompt.select(message, choices, **)
+    end
+
+    def multi_select(message, choices, **)
+      prompt.multi_select(message, choices, **)
+    end
+
+    # True when the action may proceed: --yes was given or the user confirmed in a terminal.
+    # Raises ConfirmationRequired, carrying the plan, when nobody can confirm.
+    def confirm?(summary, plan:)
+      return true if @yes
+
+      message = "#{summary}\nRe-run with --yes to confirm."
+      raise ConfirmationRequired.new(message, plan: plan) unless interactive?
+
+      prompt.proceed_with_warning(summary) { true } == true
+    end
+
+    private
+
+    def envelope(status:, plan: nil, result: nil, error: nil)
+      {
+        schema: JSON_SCHEMA_VERSION,
+        command: @command,
+        ok: OK_STATUSES.include?(status),
+        status: status,
+        dry_run: dry_run?,
+        plan: plan,
+        result: result,
+        error: error
+      }.compact
+    end
+
+    def prompt
+      @prompt ||= Prompt.create
+    end
+  end
+end

data/lib/gitflash/usage_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Gitflash
+  # Raised for invalid arguments or when input is needed but no terminal is available
+  class UsageError < Error
+    def initialize(message = nil, code: 'invalid_usage', plan: nil)
+      super
+    end
+
+    def exit_code
+      2
+    end
+  end
+end

data/lib/gitflash/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Gitflash
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/schema/v1.json

@@ -0,0 +1,172 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/Kleanthismits/git_flash/blob/main/schema/v1.json",
+  "title": "gitflash --json output, schema version 1",
+  "description": "Every gitflash command run with --json prints exactly one object in this envelope. `ok` is true for the statuses done, planned, noop and cancelled. Fields may be added in later releases of version 1; existing fields keep their meaning.",
+  "type": "object",
+  "required": ["schema", "command", "ok", "status", "dry_run"],
+  "properties": {
+    "schema": { "const": 1 },
+    "command": { "enum": ["branches", "checkout", "delete", "reset"] },
+    "ok": { "type": "boolean" },
+    "status": {
+      "description": "done: the change was made. planned: --dry-run, nothing changed. noop: nothing to do. cancelled: the user declined. failed: git refused part of the change. confirmation_required: re-run with --yes after reviewing `plan`. error: invalid input or environment.",
+      "enum": ["done", "planned", "noop", "cancelled", "failed", "confirmation_required", "error"]
+    },
+    "dry_run": { "type": "boolean" },
+    "plan": { "type": "object", "description": "The change that will be, would be or was made." },
+    "result": { "type": "object", "description": "What happened, including what is needed to revert it." },
+    "error": { "$ref": "#/$defs/error" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "status": { "enum": ["done", "planned", "noop", "cancelled"] } } },
+      "then": { "properties": { "ok": { "const": true } }, "not": { "required": ["error"] } },
+      "else": { "properties": { "ok": { "const": false } }, "required": ["error"] }
+    },
+    {
+      "if": { "properties": { "status": { "const": "confirmation_required" } } },
+      "then": { "required": ["plan"] }
+    },
+    {
+      "if": { "properties": { "command": { "const": "branches" } } },
+      "then": { "properties": { "result": { "$ref": "#/$defs/branches_result" } } }
+    },
+    {
+      "if": { "properties": { "command": { "const": "checkout" } } },
+      "then": {
+        "properties": {
+          "plan": { "$ref": "#/$defs/checkout_plan" },
+          "result": { "$ref": "#/$defs/checkout_result" }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "command": { "const": "delete" } } },
+      "then": {
+        "properties": {
+          "plan": { "$ref": "#/$defs/delete_plan" },
+          "result": { "$ref": "#/$defs/delete_result" }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "command": { "const": "reset" } } },
+      "then": {
+        "properties": {
+          "plan": { "$ref": "#/$defs/reset_plan" },
+          "result": { "$ref": "#/$defs/reset_result" }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "sha": { "type": "string", "pattern": "^[0-9a-f]{4,64}$" },
+    "error": {
+      "type": "object",
+      "required": ["code", "message", "exit_code"],
+      "properties": {
+        "code": {
+          "description": "Stable identifier to branch on; the message is for humans.",
+          "enum": [
+            "not_a_repository", "input_required", "invalid_usage", "invalid_options",
+            "unknown_branch", "unknown_commit", "protected_branch",
+            "confirmation_required", "git_failed", "failed"
+          ]
+        },
+        "message": { "type": "string" },
+        "exit_code": { "enum": [1, 2] }
+      }
+    },
+    "branch": {
+      "type": "object",
+      "required": [
+        "name", "sha", "current", "default", "upstream", "upstream_gone", "ahead", "behind",
+        "merged", "last_commit_at", "last_commit_author", "last_commit_subject"
+      ],
+      "properties": {
+        "name": { "type": "string" },
+        "sha": { "$ref": "#/$defs/sha" },
+        "current": { "type": "boolean" },
+        "default": { "type": "boolean", "description": "The branch origin/HEAD points to, else main or master." },
+        "upstream": { "type": ["string", "null"] },
+        "upstream_gone": { "type": "boolean", "description": "The upstream branch was deleted on the remote." },
+        "ahead": { "type": "integer", "minimum": 0 },
+        "behind": { "type": "integer", "minimum": 0 },
+        "merged": { "type": ["boolean", "null"], "description": "Merged into the default branch; null when there is no default branch." },
+        "last_commit_at": { "type": "string", "format": "date-time" },
+        "last_commit_author": { "type": "string" },
+        "last_commit_subject": { "type": "string" }
+      }
+    },
+    "branches_result": {
+      "type": "object",
+      "required": ["default_branch", "branches"],
+      "properties": {
+        "default_branch": { "type": ["string", "null"] },
+        "branches": { "type": "array", "items": { "$ref": "#/$defs/branch" } }
+      }
+    },
+    "checkout_plan": {
+      "type": "object",
+      "required": ["branch"],
+      "properties": { "branch": { "type": "string" } }
+    },
+    "checkout_result": {
+      "type": "object",
+      "required": ["branch", "previous_branch"],
+      "properties": {
+        "branch": { "type": ["string", "null"] },
+        "previous_branch": { "type": ["string", "null"], "description": "Check this out to go back; null on a detached HEAD." }
+      }
+    },
+    "delete_plan": {
+      "type": "object",
+      "required": ["branches", "force"],
+      "properties": {
+        "branches": { "type": "array", "items": { "type": "string" } },
+        "force": { "type": "boolean" }
+      }
+    },
+    "delete_result": {
+      "type": "object",
+      "required": ["deleted", "failed"],
+      "properties": {
+        "deleted": {
+          "type": "array",
+          "description": "Recreate a branch with: git branch NAME SHA",
+          "items": {
+            "type": "object",
+            "required": ["branch", "sha"],
+            "properties": { "branch": { "type": "string" }, "sha": { "$ref": "#/$defs/sha" } }
+          }
+        },
+        "failed": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["branch", "error"],
+            "properties": { "branch": { "type": "string" }, "error": { "type": "string" } }
+          }
+        }
+      }
+    },
+    "reset_plan": {
+      "type": "object",
+      "required": ["commit", "mode"],
+      "properties": {
+        "commit": { "$ref": "#/$defs/sha" },
+        "mode": { "enum": ["soft", "mixed", "hard"] }
+      }
+    },
+    "reset_result": {
+      "type": "object",
+      "required": ["commit", "mode", "previous_commit"],
+      "properties": {
+        "commit": { "$ref": "#/$defs/sha" },
+        "mode": { "enum": ["soft", "mixed", "hard"] },
+        "previous_commit": { "$ref": "#/$defs/sha", "description": "Reset to this commit to go back. Uncommitted changes lost by a hard reset cannot be restored this way." }
+      }
+    }
+  }
+}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gitflash
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Kleanthis Mitsioulis
@@ -73,13 +73,26 @@ files:
 - bin/gitflash
 - command_descriptions.yml
 - lib/gitflash.rb
+- lib/gitflash/branch.rb
 - lib/gitflash/cli.rb
+- lib/gitflash/commands/base.rb
+- lib/gitflash/commands/branches.rb
+- lib/gitflash/commands/checkout.rb
+- lib/gitflash/commands/delete.rb
+- lib/gitflash/commands/reset.rb
+- lib/gitflash/commit.rb
 - lib/gitflash/configuration.rb
+- lib/gitflash/confirmation_required.rb
+- lib/gitflash/error.rb
 - lib/gitflash/git/bash_command.rb
 - lib/gitflash/git/command_error.rb
-- lib/gitflash/git/wrapper.rb
 - lib/gitflash/prompt.rb
+- lib/gitflash/repo.rb
+- lib/gitflash/result.rb
+- lib/gitflash/ui.rb
+- lib/gitflash/usage_error.rb
 - lib/gitflash/version.rb
+- schema/v1.json
 homepage: https://github.com/Kleanthismits/git_flash
 licenses:
 - MIT