chocomint 1.0.0

data/lib/chocomint/console/worker_process.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "ffi"
+require "json"
+require "base64"
+require "securerandom"
+require_relative "../errors"
+
+module Chocomint
+  module Console
+    # コンソールワーカーを「新規コンソール付き」で spawn し、名前付きパイプで
+    # 双方向にやり取りするための橋渡し。
+    #
+    # なぜ名前付きパイプか (重要): ConPTY はコンソール付きプロセスからしか
+    # 正しく動かない (chocomint-conpty メモの制約)。CREATE_NEW_CONSOLE で新規
+    # コンソールを与える必要があるが、STARTF_USESTDHANDLES で stdout をパイプへ
+    # リダイレクトすると新規コンソールとの関連付けが壊れ、ConPTY 出力が 16 バイトの
+    # 初期シーケンスで止まる (実測で確認)。そこで stdio は触らず、制御通信は
+    # 独立した名前付きパイプで行う。ワーカーはコンソールを完全に保持できる。
+    class WorkerProcess
+      module Native
+        extend FFI::Library
+        ffi_lib "kernel32"
+        ffi_convention :stdcall
+
+        class ProcessInformation < FFI::Struct
+          layout :hProcess, :pointer, :hThread, :pointer, :dwProcessId, :uint32, :dwThreadId, :uint32
+        end
+
+        class StartupInfoW < FFI::Struct
+          layout(
+            :cb, :uint32, :lpReserved, :pointer, :lpDesktop, :pointer, :lpTitle, :pointer,
+            :dwX, :uint32, :dwY, :uint32, :dwXSize, :uint32, :dwYSize, :uint32,
+            :dwXCountChars, :uint32, :dwYCountChars, :uint32, :dwFillAttribute, :uint32,
+            :dwFlags, :uint32, :wShowWindow, :uint16, :cbReserved2, :uint16,
+            :lpReserved2, :pointer, :hStdInput, :pointer, :hStdOutput, :pointer, :hStdError, :pointer
+          )
+        end
+
+        CREATE_NEW_CONSOLE = 0x00000010
+        STARTF_USESHOWWINDOW = 0x00000001
+        SW_HIDE = 0
+        STILL_ACTIVE = 259
+
+        PIPE_ACCESS_DUPLEX = 0x00000003
+        PIPE_TYPE_BYTE = 0x00000000
+        PIPE_WAIT = 0x00000000
+        PIPE_REJECT_REMOTE_CLIENTS = 0x00000008
+        INVALID_HANDLE_VALUE = FFI::Pointer.new(-1)
+
+        attach_function :CreateNamedPipeW,
+                        %i[pointer uint32 uint32 uint32 uint32 uint32 uint32 pointer], :pointer
+        attach_function :ConnectNamedPipe, %i[pointer pointer], :int32
+        attach_function :DisconnectNamedPipe, [:pointer], :int32
+        attach_function :CreateProcessW,
+                        %i[pointer pointer pointer pointer int32 uint32
+                           pointer pointer pointer pointer], :int32
+        attach_function :ReadFile, %i[pointer pointer uint32 pointer pointer], :int32
+        attach_function :WriteFile, %i[pointer pointer uint32 pointer pointer], :int32
+        attach_function :PeekNamedPipe, %i[pointer pointer uint32 pointer pointer pointer], :int32
+        attach_function :GetExitCodeProcess, %i[pointer pointer], :int32
+        attach_function :TerminateProcess, %i[pointer uint32], :int32
+        attach_function :CloseHandle, [:pointer], :int32
+        attach_function :GetLastError, [], :uint32
+      end
+
+      class Error < Chocomint::Error; end
+
+      def initialize(command:, cols:, rows:, cwd:, ruby_exe: nil, worker_script: nil)
+        @command = command
+        @cols = cols
+        @rows = rows
+        @cwd = cwd
+        @ruby_exe = ruby_exe || default_ruby_exe
+        @worker_script = worker_script || default_worker_script
+        # 双方向を 1 本のパイプで共有すると read/write が競合してブロックするため、
+        # 方向ごとに 2 本張る (c2w: 親→worker, w2c: worker→親)。
+        base = "\\\\.\\pipe\\chocomint-console-#{SecureRandom.hex(8)}"
+        @c2w_name = "#{base}-c2w"
+        @w2c_name = "#{base}-w2c"
+        @open = false
+      end
+
+      def open?
+        @open
+      end
+
+      # 名前付きパイプを 2 本作り、ワーカーを新規コンソール付きで spawn して接続を待つ。
+      def start
+        raise Error, "already started" if @open
+
+        @c2w = create_named_pipe(@c2w_name)
+        @w2c = create_named_pipe(@w2c_name)
+        spawn_worker
+        # ワーカーが両パイプに接続してくるのを待つ (順序はワーカーの open と一致させる)。
+        Native.ConnectNamedPipe(@c2w, nil)
+        Native.ConnectNamedPipe(@w2c, nil)
+        @open = true
+        self
+      end
+
+      def send_message(hash)
+        write_bytes("#{JSON.generate(hash)}\n".b)
+      end
+
+      def send_input(bytes)
+        send_message("type" => "input", "data" => Base64.strict_encode64(bytes.b))
+      end
+
+      def send_resize(cols, rows)
+        send_message("type" => "resize", "cols" => cols, "rows" => rows)
+      end
+
+      # ワーカーからの JSON 行を 1 つ読む。無ければ nil (ノンブロッキング)。
+      def read_message
+        line = read_line
+        return nil if line.nil? || line.empty?
+
+        JSON.parse(line)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def alive?
+        return false unless @proc_handle
+
+        code = FFI::MemoryPointer.new(:uint32)
+        return false if Native.GetExitCodeProcess(@proc_handle, code).zero?
+
+        code.read(:uint32) == Native::STILL_ACTIVE
+      end
+
+      def close
+        return unless @open
+
+        Native.TerminateProcess(@proc_handle, 0) if alive?
+        [@c2w, @w2c].each do |h|
+          next unless h
+
+          Native.DisconnectNamedPipe(h)
+          Native.CloseHandle(h)
+        end
+        Native.CloseHandle(@proc_handle) if @proc_handle
+        @open = false
+        nil
+      end
+
+      private
+
+      def default_ruby_exe
+        require "rbconfig"
+        File.join(RbConfig::CONFIG["bindir"], RbConfig::CONFIG["ruby_install_name"])
+      end
+
+      def default_worker_script
+        File.expand_path("../../../bin/chocomint-console-worker", __dir__)
+      end
+
+      def create_named_pipe(name)
+        handle = Native.CreateNamedPipeW(
+          utf16(name),
+          Native::PIPE_ACCESS_DUPLEX,
+          Native::PIPE_TYPE_BYTE | Native::PIPE_WAIT | Native::PIPE_REJECT_REMOTE_CLIENTS,
+          1, 65_536, 65_536, 0, nil
+        )
+        if handle == Native::INVALID_HANDLE_VALUE || handle.null?
+          raise Error, "CreateNamedPipeW failed (#{Native.GetLastError})"
+        end
+
+        handle
+      end
+
+      def spawn_worker
+        si = Native::StartupInfoW.new
+        si[:cb] = Native::StartupInfoW.size
+        si[:dwFlags] = Native::STARTF_USESHOWWINDOW
+        si[:wShowWindow] = Native::SW_HIDE
+        pi = Native::ProcessInformation.new
+
+        cmd_ptr = utf16(build_command_line)
+        cwd_ptr = @cwd ? utf16(@cwd) : nil
+
+        ok = Native.CreateProcessW(
+          nil, cmd_ptr, nil, nil, 0, # stdio は継承しない (コンソールを汚さない)
+          Native::CREATE_NEW_CONSOLE, # ConPTY が動くための新規コンソール
+          nil, cwd_ptr, si.pointer, pi.pointer
+        )
+        raise Error, "CreateProcessW worker failed (#{Native.GetLastError})" if ok.zero?
+
+        @proc_handle = pi[:hProcess]
+        Native.CloseHandle(pi[:hThread])
+      end
+
+      # ruby worker.rb --c2w <name> --w2c <name> --cols .. --rows .. --cwd .. -- <shell>
+      def build_command_line
+        parts = [quote(@ruby_exe), quote(@worker_script),
+                 "--c2w", quote(@c2w_name), "--w2c", quote(@w2c_name),
+                 "--cols", @cols.to_s, "--rows", @rows.to_s]
+        parts += ["--cwd", quote(@cwd)] if @cwd
+        parts += ["--", @command]
+        parts.join(" ")
+      end
+
+      def quote(str) = %("#{str}")
+
+      def utf16(str)
+        w = str.encode("UTF-16LE").b + "\x00\x00".b
+        ptr = FFI::MemoryPointer.new(:uint8, w.bytesize)
+        ptr.put_bytes(0, w)
+        ptr
+      end
+
+      # 親→worker は c2w パイプへ書く。
+      def write_bytes(data)
+        buf = FFI::MemoryPointer.new(:uint8, data.bytesize)
+        buf.put_bytes(0, data)
+        written = FFI::MemoryPointer.new(:uint32)
+        ok = Native.WriteFile(@c2w, buf, data.bytesize, written, nil)
+        raise Error, "WriteFile pipe (#{Native.GetLastError})" if ok.zero?
+
+        written.read(:uint32)
+      end
+
+      def read_line
+        @rbuf ||= +""
+        loop do
+          if (idx = @rbuf.index("\n"))
+            return @rbuf.slice!(0..idx).chomp
+          end
+          chunk = read_available_bytes
+          return nil if chunk.nil? || chunk.empty?
+
+          @rbuf << chunk
+        end
+      end
+
+      # worker→親は w2c パイプから読む。
+      def read_available_bytes(max = 65_536)
+        avail = FFI::MemoryPointer.new(:uint32)
+        return nil if Native.PeekNamedPipe(@w2c, nil, 0, nil, avail, nil).zero?
+
+        n = avail.read(:uint32)
+        return "".b if n.zero?
+
+        want = [n, max].min
+        buf = FFI::MemoryPointer.new(:uint8, want)
+        read = FFI::MemoryPointer.new(:uint32)
+        return nil if Native.ReadFile(@w2c, buf, want, read, nil).zero?
+
+        buf.get_bytes(0, read.read(:uint32))
+      end
+    end
+  end
+end

data/lib/chocomint/edit_git_handlers.rb

@@ -0,0 +1,397 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "fileutils"
+
+module Chocomint
+  # /edit AI エディタの Git 操作ハンドラ群 (Server に include して使う)。
+  #
+  # 提供機能:
+  #   GET  /edit/git/status    初期化有無・ブランチ名・ステージ済み/未ステージのファイル一覧
+  #   POST /edit/git/init      git init
+  #   POST /edit/git/stage       ファイルをステージ (git add)
+  #   POST /edit/git/unstage     ステージ取り消し (git restore --staged)
+  #   POST /edit/git/stage_all   すべての変更をステージ (git add -A)
+  #   POST /edit/git/unstage_all すべてのステージを取り消し (git restore --staged .)
+  #   POST /edit/git/discard     変更を破棄 (追跡済みは checkout、未追跡は削除)
+  #   POST /edit/git/commit    コミット
+  #   POST /edit/git/push      push (リモート未設定なら reason: "no_remote" 付き 409 を返す)
+  #   POST /edit/git/remote    origin の URL を設定して push (未設定/差し替えの両対応)
+  #   GET  /edit/git/branches  ブランチ一覧 (現在のブランチも含む)
+  #   POST /edit/git/checkout  ブランチ切り替え/新規作成
+  #
+  # すべて edit_root (workspace ルート) を cwd にして git コマンドを実行する。
+  # workspace が git 管理下でない場合は status で初期化を促す。
+  module EditGitHandlers
+    # ---- ステータス ---------------------------------------------------------
+
+    def handle_edit_git_status(req, res)
+      return edit_method_guard(res) unless req.request_method == "GET"
+
+      unless git_repo?
+        return edit_json(res, 200, "initialized" => false)
+      end
+
+      branch = git_current_branch
+      # --untracked-files=all: 未追跡ディレクトリを 1 エントリにまとめず中のファイルを
+      # 個別に列挙させる。無指定だと "logs/" のようにディレクトリ単位でしか返らず、
+      # + ボタンでファイル単位のステージができなくなる。
+      porcelain = git_capture(%w[status --porcelain=v1 --untracked-files=all])
+      staged, unstaged = parse_git_status(porcelain)
+
+      edit_json(res, 200,
+        "initialized" => true,
+        "branch" => branch,
+        "staged" => staged,
+        "unstaged" => unstaged,
+        "remote_url" => git_remote_url)
+    rescue Chocomint::Error => e
+      edit_json(res, 500, "error" => e.message)
+    end
+
+    # git status --porcelain=v1 の各行 (XY PATH) をステージ済み/未ステージに振り分ける。
+    # X: インデックス(ステージ)の状態、Y: 作業ツリーの状態。
+    # "??" (未追跡) は unstaged 扱いにする。
+    def parse_git_status(lines)
+      staged = []
+      unstaged = []
+      lines.each do |line|
+        next if line.length < 4
+
+        x = line[0]
+        y = line[1]
+        path = line[3..].to_s.tr("\\", "/")
+        # rename は "R  old -> new" の形式。表示・操作対象は new 側のパス。
+        path = path.split(" -> ").last if path.include?(" -> ")
+
+        staged << { "path" => path, "status" => x } if x != " " && x != "?"
+        unstaged << { "path" => path, "status" => y } if y != " " || x == "?"
+      end
+      [staged, unstaged]
+    end
+
+    # ---- 初期化 ---------------------------------------------------------------
+
+    def handle_edit_git_init(req, res)
+      return edit_method_guard(res) unless req.request_method == "POST"
+
+      if git_repo?
+        return edit_json(res, 400, "error" => "既に git 管理下です")
+      end
+
+      out, err, status = git_run(%w[init])
+      return edit_json(res, 500, "error" => err.empty? ? out : err) unless status.success?
+
+      edit_json(res, 200, "initialized" => true, "branch" => git_current_branch)
+    rescue Chocomint::Error => e
+      edit_json(res, 500, "error" => e.message)
+    end
+
+    # ---- ステージ / 取り消し ---------------------------------------------------
+
+    def handle_edit_git_stage(req, res)
+      return edit_method_guard(res) unless req.request_method == "POST"
+
+      with_git(res) do
+        require_git_repo!
+        paths = git_body_paths(req)
+        out, err, status = git_run(["add", "--"] + paths)
+        raise Chocomint::Error, (err.empty? ? out : err) unless status.success?
+
+        edit_json(res, 200, "staged" => paths)
+      end
+    end
+
+    def handle_edit_git_unstage(req, res)
+      return edit_method_guard(res) unless req.request_method == "POST"
+
+      with_git(res) do
+        require_git_repo!
+        paths = git_body_paths(req)
+        out, err, status = unstage_paths(paths)
+        raise Chocomint::Error, (err.empty? ? out : err) unless status.success?
+
+        edit_json(res, 200, "unstaged" => paths)
+      end
+    end
+
+    def handle_edit_git_stage_all(req, res)
+      return edit_method_guard(res) unless req.request_method == "POST"
+
+      with_git(res) do
+        require_git_repo!
+        out, err, status = git_run(%w[add -A])
+        raise Chocomint::Error, (err.empty? ? out : err) unless status.success?
+
+        edit_json(res, 200, "staged_all" => true)
+      end
+    end
+
+    def handle_edit_git_unstage_all(req, res)
+      return edit_method_guard(res) unless req.request_method == "POST"
+
+      with_git(res) do
+        require_git_repo!
+        out, err, status = unstage_paths(%w[.])
+        raise Chocomint::Error, (err.empty? ? out : err) unless status.success?
+
+        edit_json(res, 200, "unstaged_all" => true)
+      end
+    end
+
+    # ---- 変更の破棄 ---------------------------------------------------------------
+    #
+    # 追跡済みファイルの変更は `git restore` で元に戻し、未追跡ファイルはワークツリーから
+    # 削除する (git 管理下に無いため restore では戻せない)。ディレクトリ丸ごとの未追跡も
+    # 同様に削除する。ステージ済みの変更はまず取り消してから破棄する (add 済みでも作業ツリーを戻す)。
+    def handle_edit_git_discard(req, res)
+      return edit_method_guard(res) unless req.request_method == "POST"
+
+      with_git(res) do
+        require_git_repo!
+        paths = git_body_paths(req)
+        discard_paths(paths)
+        edit_json(res, 200, "discarded" => paths)
+      end
+    end
+
+    def discard_paths(paths)
+      tracked, untracked = paths.partition { |p| git_tracked?(p) }
+
+      unless tracked.empty?
+        unstage_paths(tracked)
+        _out, err, status = git_run(["restore", "--"] + tracked)
+        raise Chocomint::Error, (err.empty? ? "変更の破棄に失敗しました" : err) unless status.success?
+      end
+
+      untracked.each do |p|
+        abs = @path_guard.resolve(p)
+        FileUtils.rm_rf(abs)
+      end
+    end
+
+    # ステージ済みの変更を取り消す。`git restore --staged` は初回コミット前
+    # (HEAD が無い) だと "fatal: could not resolve HEAD" で失敗するため、
+    # その場合は index をリセットする `git reset` にフォールバックする。
+    def unstage_paths(paths)
+      out, err, status = git_run(["restore", "--staged", "--"] + paths)
+      return [out, err, status] if status.success?
+
+      git_run(["reset", "--"] + paths)
+    end
+
+    def git_tracked?(path)
+      _out, _err, status = git_run(["ls-files", "--error-unmatch", "--", path])
+      status.success?
+    end
+
+    # ---- コミット ---------------------------------------------------------------
+
+    def handle_edit_git_commit(req, res)
+      return edit_method_guard(res) unless req.request_method == "POST"
+
+      with_git(res) do
+        require_git_repo!
+        body = JSON.parse(req.body.to_s)
+        message = body["message"].to_s.strip
+        raise Chocomint::Error, "コミットメッセージが必要です" if message.empty?
+
+        out, err, status = git_run(["commit", "-m", message])
+        raise Chocomint::Error, (err.empty? ? out : err) unless status.success?
+
+        edit_json(res, 200, "committed" => true, "branch" => git_current_branch)
+      end
+    end
+
+    # ---- push ---------------------------------------------------------------
+
+    def handle_edit_git_push(req, res)
+      return edit_method_guard(res) unless req.request_method == "POST"
+
+      unless git_repo?
+        return edit_json(res, 400, "error" => "git 管理下ではありません")
+      end
+
+      out, err, status = git_run(%w[push])
+      return edit_json(res, 200, "pushed" => true, "output" => (err.empty? ? out : err)) if status.success?
+
+      message = err.empty? ? out : err
+      # リモート/上流ブランチが未設定だと push は失敗する。フロントはこの reason で
+      # 「リモート URL を入力させるダイアログ」に切り替える (エラーダイアログではなく)。
+      if push_target_missing?(message)
+        return edit_json(res, 409, "error" => message, "reason" => "no_remote")
+      end
+
+      edit_json(res, 400, "error" => message)
+    rescue JSON::ParserError => e
+      edit_json(res, 400, "error" => "invalid JSON: #{e.message}")
+    rescue Chocomint::Error => e
+      edit_json(res, 500, "error" => e.message)
+    end
+
+    # push 先が無いことを示すエラー文言か判定する (リモート未設定 / 上流ブランチ未設定の両方)。
+    def push_target_missing?(message)
+      message.include?("No configured push destination") ||
+        message.include?("has no upstream branch")
+    end
+
+    # ---- リモート ---------------------------------------------------------------
+
+    def handle_edit_git_remote_set(req, res)
+      return edit_method_guard(res) unless req.request_method == "POST"
+
+      with_git(res) do
+        require_git_repo!
+        body = JSON.parse(req.body.to_s)
+        url = body["url"].to_s.strip
+        raise Chocomint::Error, "リモート URL を入力してください" if url.empty?
+
+        # 既に origin が設定されていれば URL を差し替え、無ければ新規に追加する。
+        if git_remote_url
+          out, err, status = git_run(%w[remote set-url origin] + [url])
+        else
+          out, err, status = git_run(%w[remote add origin] + [url])
+        end
+        raise Chocomint::Error, (err.empty? ? out : err) unless status.success?
+
+        # 上流ブランチも合わせて設定しつつ push する (初回 push は -u が無いと
+        # "has no upstream branch" で失敗するため)。
+        branch = git_current_branch
+        out, err, status = git_run(["push", "-u", "origin", branch])
+        raise Chocomint::Error, (err.empty? ? out : err) unless status.success?
+
+        edit_json(res, 200, "pushed" => true, "remote_url" => url, "output" => (err.empty? ? out : err))
+      end
+    end
+
+    # ---- ブランチ ---------------------------------------------------------------
+
+    def handle_edit_git_branches(req, res)
+      return edit_method_guard(res) unless req.request_method == "GET"
+
+      unless git_repo?
+        return edit_json(res, 400, "error" => "git 管理下ではありません")
+      end
+
+      out = git_capture(%w[branch --list])
+      branches = out.map { |l| l.sub(/\A\*?\s*/, "").strip }.reject(&:empty?)
+      current = git_current_branch
+      # コミットが一つも無いブランチ (init 直後など) は `git branch --list` に
+      # 現れないため、現在のブランチが漏れていれば一覧に加えて必ず選択肢に見せる。
+      branches.unshift(current) if current && !branches.include?(current)
+      edit_json(res, 200, "branches" => branches, "current" => current)
+    rescue Chocomint::Error => e
+      edit_json(res, 500, "error" => e.message)
+    end
+
+    def handle_edit_git_checkout(req, res)
+      return edit_method_guard(res) unless req.request_method == "POST"
+
+      with_git(res) do
+        require_git_repo!
+        body = JSON.parse(req.body.to_s)
+        branch = body["branch"].to_s.strip
+        create = !!body["create"]
+        raise Chocomint::Error, "branch required" if branch.empty?
+
+        args = create ? ["checkout", "-b", branch] : ["checkout", branch]
+        out, err, status = git_run(args)
+        unless status.success?
+          message = err.empty? ? out : err
+          # ブランチ参照が見つからない場合、原因は「名前が間違っている」か
+          # 「切替先にまだコミットが一つも無く Git 上に実体化していない」のどちらか
+          # (エラー文言だけでは判別できない) なので、両方の可能性を伝える。
+          if !create && (message.include?("invalid reference") || message.include?("did not match"))
+            message += "\n(ブランチ名の誤り、またはコミットが一つも無い空のブランチのため" \
+                        "切り替えられていない可能性があります。空のブランチは最初のコミットを" \
+                        "するまで Git 上に実体化しません。)"
+          end
+          raise Chocomint::Error, message
+        end
+
+        edit_json(res, 200, "branch" => git_current_branch)
+      end
+    end
+
+    # ---- 補助 ---------------------------------------------------------------
+
+    # Open3::Status 互換 (success? だけ呼べれば良い) の失敗ダミー。
+    # git コマンド自体が見つからない (Errno::ENOENT) 場合に使う。
+    class GitCommandNotFoundStatus
+      def success? = false
+    end
+    GIT_NOT_FOUND = GitCommandNotFoundStatus.new.freeze
+
+    # edit_root 自身が git リポジトリのトップレベルである場合のみ true を返す。
+    # workspace が祖先ディレクトリの .git を継承しているだけ (workspace 自体は
+    # 管理下に無い) だと git コマンドはその祖先リポジトリに対して動いてしまう
+    # ため、show-toplevel が edit_root と一致するかまで確認する。
+    def git_repo?
+      out, _err, status = git_run(%w[rev-parse --show-toplevel])
+      return false unless status.success?
+
+      same_path?(out.strip, edit_root)
+    end
+
+    # git の出力 (常に "/" 区切り) と Ruby 側の絶対パスを比較する。
+    # Windows はドライブレターの大小文字揺れがあるため大文字小文字を無視する。
+    def same_path?(git_path, ruby_path)
+      normalize_path(git_path) == normalize_path(ruby_path)
+    end
+
+    def normalize_path(path)
+      File.expand_path(path).tr("\\", "/").downcase
+    end
+
+    def git_current_branch
+      out, _err, status = git_run(%w[branch --show-current])
+      status.success? ? out.strip : nil
+    end
+
+    # origin の URL (未設定なら nil)。
+    def git_remote_url
+      out, _err, status = git_run(%w[remote get-url origin])
+      status.success? ? out.strip : nil
+    end
+
+    # git コマンドを edit_root で実行し [stdout, stderr, Process::Status] を返す。
+    def git_run(args)
+      Open3.capture3("git", *args, chdir: edit_root)
+    rescue Errno::ENOENT
+      ["", "git コマンドが見つかりません", GIT_NOT_FOUND]
+    end
+
+    # 成功時の stdout を行配列で返す (失敗時は空配列)。
+    def git_capture(args)
+      out, _err, status = git_run(args)
+      status.success? ? out.each_line.map(&:chomp) : []
+    end
+
+    # JSON ボディから "paths" (配列) または "path" (単一) を取り出す。
+    def git_body_paths(req)
+      body = JSON.parse(req.body.to_s)
+      paths = Array(body["paths"] || body["path"]).map(&:to_s).reject(&:empty?)
+      raise Chocomint::Error, "path(s) required" if paths.empty?
+
+      paths
+    end
+
+    # edit_root がリポジトリのトップレベルでなければ拒否する。init/checkout 以外の
+    # 全操作の先頭で呼び、祖先ディレクトリの .git を誤って操作しないようにする。
+    def require_git_repo!
+      raise Chocomint::Error, "git 管理下ではありません" unless git_repo?
+    end
+
+    # Git 操作系ハンドラ共通の例外→HTTP 変換。
+    def with_git(res)
+      yield
+    rescue JSON::ParserError => e
+      edit_json(res, 400, "error" => "invalid JSON: #{e.message}")
+    rescue Chocomint::Error => e
+      edit_json(res, 400, "error" => e.message)
+    rescue SystemCallError => e
+      edit_json(res, 500, "error" => e.message)
+    end
+  end
+end