gitbroker 0.3.0

data/lib/gitbroker/hooks_installer.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "rbconfig"
+require "shellwords"
+
+module Gitbroker
+  # Adds `gitbroker hook <event>` command hooks to the user-level Claude Code settings (opt-in, main spec §18.4).
+  # Merges into the existing file: every other setting and the user's own hooks stay, our entries are replaced (never
+  # duplicated), an unchanged file is not rewritten, and a changed one is backed up first. No token is ever written.
+  class HooksInstaller
+    EVENTS = %w[SessionStart UserPromptSubmit Stop SessionEnd].freeze
+    OURS = /gitbroker hook (?:#{EVENTS.join("|")})\z/
+    TIMEOUT = 5
+
+    attr_reader :settings_path
+
+    def self.default(env: ENV, home: Dir.home)
+      new(settings_path: File.join(env["CLAUDE_CONFIG_DIR"] || File.join(home, ".claude"), "settings.json"),
+          command_prefix: "#{Shellwords.escape(RbConfig.ruby)} #{Shellwords.escape(ServiceInstaller::EXE)}")
+    end
+
+    def initialize(settings_path:, command_prefix:, clock: -> { Time.now })
+      @settings_path = settings_path
+      @command_prefix = command_prefix
+      @clock = clock
+    end
+
+    def installed?
+      hooks = read["hooks"] || {}
+      EVENTS.all? { |event| Array(hooks[event]).any? { ours_group?(_1) } }
+    end
+
+    # Returns the backup path, or nil when there was nothing to back up (new file) or nothing changed.
+    def install!
+      data = read
+      hooks = strip_ours(data["hooks"] || {})
+      EVENTS.each { |event| hooks[event] = Array(hooks[event]) + [ group_for(event) ] }
+      write(data, data.merge("hooks" => hooks))
+    end
+
+    def uninstall!
+      return nil unless File.exist?(settings_path)
+
+      data = read
+      return nil unless data.key?("hooks")
+
+      hooks = strip_ours(data["hooks"]).reject { |_event, groups| groups.empty? }
+      updated = data.dup
+      hooks.empty? ? updated.delete("hooks") : updated["hooks"] = hooks
+      write(data, updated)
+    end
+
+    private
+
+    def group_for(event) = { "hooks" => [ { "type" => "command", "command" => "#{@command_prefix} hook #{event}", "timeout" => TIMEOUT } ] }
+    def ours_hook?(hook) = hook.is_a?(Hash) && hook["command"].to_s.match?(OURS)
+    def ours_group?(group) = group.is_a?(Hash) && Array(group["hooks"]).any? { ours_hook?(_1) }
+
+    def strip_ours(hooks)
+      hooks.to_h do |event, groups|
+        kept = Array(groups).filter_map do |group|
+          next group unless group.is_a?(Hash) && group["hooks"].is_a?(Array)
+
+          remaining = group["hooks"].reject { ours_hook?(_1) }
+          next nil if remaining.empty? && group["hooks"].any?
+
+          group.merge("hooks" => remaining)
+        end
+        [ event, kept ]
+      end
+    end
+
+    def read
+      return {} unless File.exist?(settings_path)
+
+      data = JSON.parse(File.read(settings_path))
+      raise Error, "#{settings_path} is not a JSON object; fix it first (nothing was changed)" unless data.is_a?(Hash)
+      unless data["hooks"].nil? || data["hooks"].is_a?(Hash)
+        raise Error, "#{settings_path} has a \"hooks\" value that is not an object; fix it first (nothing was changed)"
+      end
+
+      data
+    rescue JSON::ParserError
+      raise Error, "#{settings_path} is not valid JSON; fix it first (nothing was changed)"
+    end
+
+    def write(before, after)
+      exists = File.exist?(settings_path)
+      return nil if exists && before == after
+
+      FileUtils.mkdir_p(File.dirname(settings_path))
+      backup = exists ? backup! : nil
+      temp = "#{settings_path}.gitbroker-#{Process.pid}.tmp"
+      File.write(temp, "#{JSON.pretty_generate(after)}\n")
+      File.chmod(File.stat(settings_path).mode & 0o777, temp) if exists
+      File.rename(temp, settings_path)
+      backup
+    ensure
+      FileUtils.rm_f(temp) if temp
+    end
+
+    # Never overwrites an earlier backup, even within the same second.
+    def backup!
+      base = "#{settings_path}.gitbroker-backup-#{@clock.call.utc.strftime("%Y%m%d%H%M%S")}"
+      path = base
+      counter = 0
+      path = "#{base}-#{counter += 1}" while File.exist?(path)
+      FileUtils.cp(settings_path, path, preserve: true)
+      path
+    end
+  end
+end

data/lib/gitbroker/launcher.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "shellwords"
+require "yaml"
+require "fileutils"
+
+module Gitbroker
+  # Opens a visible terminal running the task's run script (spec §4.2 step 6). The user sees and drives the agent.
+  class Launcher
+    def initialize(name:, runner: Runner.new, platform: Gitbroker.platform,
+                   warp_dir: File.join(Dir.home, ".warp", "launch_configurations"))
+      raise Error, "Unknown terminal #{name.inspect}. Use one of: #{Config::TERMINALS.join(", ")}" unless Config::TERMINALS.include?(name)
+
+      @name = name
+      @runner = runner
+      @platform = platform
+      @warp_dir = warp_dir
+    end
+
+    def launch!(script:, cwd:, title:)
+      commands(script:, cwd:, title:).each { @runner.run!(*_1) }
+    end
+
+    def commands(script:, cwd:, title:)
+      title = title.to_s.gsub(/[^\w.#-]/, "-")
+      line = "/bin/bash #{Shellwords.escape(script)}"
+
+      case @name
+      when "terminal"
+        [ [ "osascript", "-e", %(tell application "Terminal" to do script #{applescript(line)}),
+            "-e", %(tell application "Terminal" to activate) ] ]
+      when "iterm2"
+        [ [ "osascript", "-e", %(tell application "iTerm" to create window with default profile command #{applescript(line)}),
+            "-e", %(tell application "iTerm" to activate) ] ]
+      when "ghostty"
+        @platform == "macos" ? [ [ "open", "-na", "Ghostty", "--args", "-e", "/bin/bash", script ] ] : [ [ "ghostty", "-e", "/bin/bash", script ] ]
+      when "warp"
+        [ [ @platform == "macos" ? "open" : "xdg-open", "warp://launch/#{warp_config(line:, cwd:, title:)}" ] ]
+      when "tmux"
+        if @runner.success?("tmux", "has-session")
+          [ [ "tmux", "new-window", "-n", title, "-c", cwd, line ] ]
+        else
+          [ [ "tmux", "new-session", "-d", "-s", "gitbroker", "-n", title, "-c", cwd, line ] ]
+        end
+      end
+    end
+
+    private
+
+    # An AppleScript string literal: backslashes and double quotes escaped.
+    def applescript(text) = %("#{text.gsub("\\") { "\\\\" }.gsub('"') { '\\"' }}")
+
+    def warp_config(line:, cwd:, title:)
+      FileUtils.mkdir_p(@warp_dir)
+      file = "gitbroker-#{title}.yaml"
+      config = { "name" => "GitBroker #{title}",
+                 "windows" => [ { "tabs" => [ { "title" => title, "layout" => { "cwd" => cwd, "commands" => [ { "exec" => line } ] } } ] } ] }
+      File.write(File.join(@warp_dir, file), config.to_yaml)
+      file
+    end
+  end
+end

data/lib/gitbroker/lifecycle.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "rbconfig"
+
+module Gitbroker
+  # Stopping, restarting and spawning the companion on this machine: used by `gitbroker stop` / `restart` / `launch` and
+  # by the daemon when the website sends a "control" message. A background service (launchd / systemd) is stopped and
+  # restarted through its manager, otherwise it would resurrect a stopped daemon (KeepAlive / Restart=always).
+  class Lifecycle
+    PID_FILE = "daemon.pid"
+    WAIT = 10
+
+    def initialize(dir:, home: Dir.home, service: ServiceInstaller.new(home:), runner: Runner.new, exe: ServiceInstaller::EXE,
+                   ruby: RbConfig.ruby, spawner: nil, sleeper: ->(seconds) { sleep(seconds) }, pid: Process.pid)
+      @dir = dir
+      @home = home
+      @service = service
+      @runner = runner
+      @exe = exe
+      @ruby = ruby
+      @spawner = spawner || method(:spawn_process)
+      @sleeper = sleeper
+      @pid = pid
+    end
+
+    def pid_path = File.join(@dir, PID_FILE)
+    def service_installed? = @service.installed?
+    def log_path = File.join(@home, ".config", "gitbroker", "companion.log")
+
+    def write_pid
+      FileUtils.mkdir_p(@dir)
+      File.write(pid_path, @pid.to_s)
+    end
+
+    def clear_pid
+      File.delete(pid_path) if File.exist?(pid_path) && File.read(pid_path).to_i == @pid
+    rescue SystemCallError
+      nil
+    end
+
+    # Used by the daemon itself: false when no service is installed or the manager refused.
+    def stop_service = @service.installed? && @service.stop!
+    def restart_service = @service.installed? && @service.restart!
+
+    # Starts the background service, or the daemon itself when none is installed. False when a service was refused.
+    def launch
+      return true if @service.start!
+
+      spawn_daemon
+    end
+
+    def spawn_daemon
+      FileUtils.mkdir_p(File.dirname(log_path))
+      @spawner.call([ @ruby, @exe, "start" ], log_path)
+      true
+    end
+
+    # The service (if any) is stopped through its manager; a daemon started by hand is signalled by its pid file.
+    def stop
+      stopped = @service.installed? && @service.stop!
+      terminated = terminate_running
+      stopped || terminated
+    end
+
+    # Through the manager when a service is installed (it loads the freshly installed gem), otherwise stop and start again.
+    def restart
+      return true if @service.installed? && @service.restart!
+
+      terminate_running
+      spawn_daemon
+    end
+
+    # The running daemon's pid, only when it is alive and really a gitbroker process (a stale file may name a recycled pid).
+    def running_pid
+      pid = File.exist?(pid_path) ? File.read(pid_path).to_i : 0
+      return nil if pid <= 1 || pid == @pid
+
+      Process.kill(0, pid)
+      @runner.capture("ps", "-p", pid.to_s, "-o", "command=").include?("gitbroker") ? pid : nil
+    rescue SystemCallError
+      nil
+    end
+
+    private
+
+    def terminate_running
+      pid = running_pid
+      return false unless pid
+
+      Process.kill("TERM", pid)
+      WAIT.times do
+        return true unless alive?(pid)
+
+        @sleeper.call(0.5)
+      end
+      Process.kill("KILL", pid) if alive?(pid)
+      true
+    rescue SystemCallError
+      false
+    end
+
+    def alive?(pid)
+      Process.kill(0, pid)
+      true
+    rescue SystemCallError
+      false
+    end
+
+    def spawn_process(argv, log)
+      Process.detach(Process.spawn(*argv, in: File::NULL, out: [ log, "a" ], err: [ log, "a" ], pgroup: true))
+    end
+  end
+end

data/lib/gitbroker/local_relay.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "socket"
+require "json"
+require "io/wait"
+require "fileutils"
+
+module Gitbroker
+  # Unix socket between `gitbroker hook` (one JSON object per line) and the daemon. Owner-only (0600); the daemon
+  # forwards over its authenticated Action Cable connection.
+  class LocalRelay
+    MAX_LINE = 4_096
+    MAX_QUEUE = 1_000
+
+    attr_reader :path
+
+    def self.send_line(path, line, timeout: 0.2)
+      return false unless File.socket?(path)
+
+      socket = Socket.new(:UNIX, :STREAM)
+      begin
+        socket.connect_nonblock(Socket.sockaddr_un(path))
+      rescue IO::WaitWritable
+        return false unless socket.wait_writable(timeout)
+      end
+      written = socket.write_nonblock("#{line}\n", exception: false)
+      return false if written == :wait_writable && !socket.wait_writable(timeout)
+
+      true
+    rescue SystemCallError, IOError, ArgumentError
+      false
+    ensure
+      socket&.close
+    end
+
+    def initialize(path:)
+      @path = path
+      @queue = Queue.new
+    end
+
+    def start
+      if File.exist?(@path)
+        raise Error, "Another gitbroker daemon is already running (#{@path})" if self.class.send_line(@path, "{}", timeout: 0.1)
+
+        File.delete(@path)
+      end
+      FileUtils.mkdir_p(File.dirname(@path), mode: 0o700)
+      previous = File.umask(0o177)
+      begin
+        @server = UNIXServer.new(@path)
+      ensure
+        File.umask(previous)
+      end
+      File.chmod(0o600, @path)
+      @thread = Thread.new { accept_loop }
+      self
+    end
+
+    def drain
+      items = []
+      items << @queue.pop(true) while items.size < MAX_QUEUE && !@queue.empty?
+      items
+    rescue ThreadError
+      items
+    end
+
+    # Only a relay that started removes the socket file, so a failed start never unlinks a live daemon's socket.
+    def stop
+      return unless @server
+
+      @server.close
+      @thread&.kill
+      File.delete(@path) if File.socket?(@path)
+      @server = nil
+    rescue IOError, SystemCallError
+      nil
+    end
+
+    private
+
+    def accept_loop
+      loop { read_client(@server.accept) }
+    rescue IOError, SystemCallError
+      nil
+    end
+
+    def read_client(client)
+      return unless client.wait_readable(1)
+
+      line = client.gets(MAX_LINE)
+      data = line && JSON.parse(line)
+      # `{}` is the liveness probe from #start; empty objects are dropped.
+      @queue << data if data.is_a?(Hash) && !data.empty? && @queue.size < MAX_QUEUE
+    rescue JSON::ParserError, IOError, SystemCallError
+      nil
+    ensure
+      client.close
+    end
+  end
+end

data/lib/gitbroker/login.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Gitbroker
+  # RFC 8628-style device-code pairing against POST /device_authorizations (spec §4.1).
+  class Login
+    def self.open_browser(url)
+      system(Gitbroker.platform == "macos" ? "open" : "xdg-open", url, out: File::NULL, err: File::NULL)
+    end
+
+    def initialize(config:, api: Api.new(server: config.server), out: $stdout, name: Socket.gethostname,
+                   sleeper: ->(seconds) { sleep(seconds) }, opener: ->(url) { Login.open_browser(url) }, clock: -> { Time.now })
+      @config = config
+      @api = api
+      @out = out
+      @name = name
+      @sleeper = sleeper
+      @opener = opener
+      @clock = clock
+    end
+
+    def run
+      auth = @api.post("/device_authorizations", { client_name: @name, platform: Gitbroker.platform })
+      # No pre-filled link: the user types the code on the plain page.
+      @out.puts "To pair this machine, open #{auth.fetch("verification_uri")} and type the code: #{auth.fetch("user_code")}"
+      @out.puts "Approve only if the page shows this machine's name (#{@name}) and the code above."
+      @opener.call(auth.fetch("verification_uri"))
+      poll(auth)
+    end
+
+    private
+
+    def poll(auth)
+      interval = auth.fetch("interval", 5).to_i
+      deadline = @clock.call + auth.fetch("expires_in", 600).to_i
+
+      loop do
+        raise Error, "The pairing code expired. Run `gitbroker login` again." if @clock.call > deadline
+
+        @sleeper.call(interval)
+        begin
+          # RFC 8628: the device code goes in the body, never the URL (request paths end up in logs).
+          token = @api.post("/device_authorizations/token", { device_code: auth.fetch("device_code") })
+        rescue Api::HttpError => e
+          case e.body["error"]
+          when "authorization_pending" then next
+          when "slow_down" then interval += 5
+          when "expired_token" then raise Error, "The pairing code expired. Run `gitbroker login` again."
+          else raise Error, "Pairing failed: #{e.message}"
+          end
+          next
+        end
+
+        @config.save_credentials!(device_token: token.fetch("access_token"), device_id: token.fetch("device_id"))
+        @out.puts "Paired. Next: `gitbroker install-service` (or `gitbroker start`)."
+        return token["device_id"]
+      end
+    end
+  end
+end

data/lib/gitbroker/neutralizer.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Gitbroker
+  # Untrusted heads only (spec §4.2 step 3, §5.1; understanding spec §5.3): the PR's own agent configuration never
+  # becomes active. Repo-controlled config is removed (restoring it from base is not enough: base hooks would still
+  # run); CLAUDE.md / AGENTS.md come back from the base branch. Every touched tracked path is marked --skip-worktree,
+  # so `git add -A` can never commit the neutralization.
+  class Neutralizer
+    CONFIG_DIRS = %w[.claude .codex].freeze
+    REMOVE = [ *CONFIG_DIRS.flat_map { [ ":(glob)**/#{_1}", ":(glob)**/#{_1}/**" ] }, ":(glob)**/.mcp.json",
+               ":(glob)**/AGENTS.override.md", ":(glob)**/CLAUDE.local.md", ":(glob)**/.gitattributes" ].freeze
+    RESTORE = [ ":(glob)**/CLAUDE.md", ":(glob)**/AGENTS.md" ].freeze
+
+    def initialize(runner: Runner.new)
+      @runner = runner
+    end
+
+    def neutralize!(dir, repo_path:, number:, base_ref:)
+      raise Error, "Invalid base branch #{base_ref.inspect}" unless Worktree.valid_ref?(base_ref)
+      raise Error, "Invalid PR number #{number.inspect}" unless number.to_s.match?(/\A[1-9]\d{0,9}\z/)
+
+      @dir = File.realpath(dir)
+      base = "refs/gitbroker/base-#{number}"
+      @runner.git(repo_path, "fetch", "--quiet", "origin", "+refs/heads/#{base_ref}:#{base}")
+
+      removed = paths(@runner.git(@dir, "ls-files", "-z", "--", *REMOVE))
+      removed.each { delete(_1) }
+      removed += untracked_config
+      (CONFIG_DIRS + [ ".mcp.json" ]).each { delete(_1, recursive: true) }
+
+      restored = restore_from(base)
+      touched = (removed + restored).uniq
+      tracked = touched.empty? ? [] : paths(@runner.git(@dir, "ls-files", "-z", "--", *touched.map { ":(literal)#{_1}" }))
+      @runner.git(@dir, "update-index", "--skip-worktree", "--", *tracked) if tracked.any?
+      touched.sort
+    end
+
+    private
+
+    # CLAUDE.md / AGENTS.md the PR modified come back from base; ones it added are deleted. Ones it deleted stay
+    # deleted: restored, they would be untracked files that `git add -A` could commit.
+    def restore_from(base)
+      fields = paths(@runner.git(@dir, "diff", "-z", "--name-status", "--no-renames", "#{base}...HEAD", "--", *RESTORE))
+      fields.each_slice(2).filter_map do |status, path|
+        case status
+        when "A" then delete(path)
+        when "D" then next
+        else @runner.git(@dir, "restore", "--source=#{base}", "--worktree", "--", ":(literal)#{path}")
+        end
+        path
+      end
+    end
+
+    # Untracked agent config at the top of the worktree (never from the PR, but never trusted either).
+    def untracked_config
+      (CONFIG_DIRS + [ ".mcp.json" ]).flat_map do |name|
+        path = File.join(@dir, name)
+        next [] unless File.exist?(path) && !File.symlink?(path)
+        next [ name ] unless File.directory?(path)
+
+        Dir.glob("**/*", File::FNM_DOTMATCH, base: path).reject { File.directory?(File.join(path, _1)) }.map { "#{name}/#{_1}" }
+      end
+    end
+
+    # Only ever deletes inside the worktree: a path whose parent resolves elsewhere (a symlinked directory) is skipped.
+    def delete(relative, recursive: false)
+      full = File.join(@dir, relative)
+      parent = File.realpath(File.dirname(full))
+      return unless parent == @dir || parent.start_with?("#{@dir}/")
+
+      recursive ? FileUtils.rm_rf(full) : FileUtils.rm_f(full)
+    rescue SystemCallError
+      nil
+    end
+
+    def paths(output) = output.split("\0").reject(&:empty?)
+  end
+end

data/lib/gitbroker/process_scanner.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Gitbroker
+  # Every tick (30 s): which known coding agents run, and in which GitHub checkout. A process says nothing about
+  # working or waiting, so this reports only "running" and "exit" (main spec §18.4). A process's cwd is untrusted:
+  # it is resolved from .git files only, never by running git there.
+  class ProcessScanner
+    AGENTS = { "claude" => "claude_code", "codex" => "codex", "aider" => "aider", "cursor-agent" => "cursor" }.freeze
+    LAUNCHERS = /\A(?:node|python[\d.]*|bun|deno)\z/
+
+    def self.agent_for(args)
+      tokens = args.to_s.split
+      name = File.basename(tokens[0].to_s)
+      name = File.basename(tokens[1].to_s) if name.match?(LAUNCHERS)
+      AGENTS[name.sub(/\.(?:js|mjs|cjs|py)\z/, "")]
+    end
+
+    # skip_claude: true/false, or a callable checked on every scan (Claude sessions with hooks installed report
+    # themselves, with real working/waiting status).
+    def initialize(runner: Runner.new, platform: Gitbroker.platform, skip_claude: false, exclude: [], proc_root: "/proc",
+                   resolver: ->(cwd) { GitContext.resolve(cwd) }, clock: -> { Time.now })
+      @runner = runner
+      @platform = platform
+      @skip_claude = skip_claude
+      @exclude = exclude.map { File.expand_path(_1) }
+      @proc_root = proc_root
+      @resolver = resolver
+      @clock = clock
+      @known = {}
+    end
+
+    def scan
+      now = @clock.call.utc.iso8601
+      current = live_agents
+      running = current.map do |id, info|
+        { "event" => "running", "agent" => info[:agent], "external_session_id" => id, "occurred_at" => now }.merge(info[:context])
+      end
+      exited = (@known.keys - current.keys).map do |id|
+        { "event" => "exit", "agent" => @known[id], "external_session_id" => id, "occurred_at" => now }
+      end
+      @known = current.transform_values { _1[:agent] }
+      running + exited
+    end
+
+    private
+
+    # { "proc-<pid>" => { agent:, context: } }, one per (agent, cwd), only in GitHub checkouts outside `exclude`.
+    def live_agents
+      agents = agent_processes
+      cwds = working_dirs(agents.keys)
+      seen = {}
+      agents.sort.each_with_object({}) do |(pid, agent), current|
+        cwd = cwds[pid]
+        next if cwd.nil? || seen[[ agent, cwd ]] || excluded?(cwd)
+
+        context = @resolver.call(cwd) or next
+        seen[[ agent, cwd ]] = true
+        current["proc-#{pid}"] = { agent:, context: }
+      end
+    end
+
+    def skip_claude? = @skip_claude.respond_to?(:call) ? @skip_claude.call : @skip_claude
+    def excluded?(cwd) = @exclude.any? { cwd == _1 || cwd.start_with?("#{_1}/") }
+
+    def agent_processes
+      skip_claude = skip_claude?
+      @runner.run!("ps", "-Ao", "pid=,args=").lines.each_with_object({}) do |line, found|
+        pid, args = line.strip.split(" ", 2)
+        next unless pid.to_s.match?(/\A\d+\z/) && pid.to_i != Process.pid
+
+        agent = self.class.agent_for(args)
+        next if agent.nil? || (skip_claude && agent == "claude_code")
+
+        found[pid.to_i] = agent
+      end
+    rescue Error
+      {}
+    end
+
+    def working_dirs(pids)
+      return {} if pids.empty?
+      return pids.to_h { [ _1, proc_cwd(_1) ] }.compact if @platform == "linux"
+
+      cwds = {}
+      pid = nil
+      @runner.capture("lsof", "-a", "-d", "cwd", "-Fn", "-p", pids.sort.join(",")).each_line do |line|
+        case line[0]
+        when "p" then pid = line[1..].to_i
+        when "n" then cwds[pid] = line[1..].chomp if pid
+        end
+      end
+      cwds
+    end
+
+    def proc_cwd(pid)
+      File.readlink(File.join(@proc_root, pid.to_s, "cwd"))
+    rescue SystemCallError
+      nil
+    end
+  end
+end

data/lib/gitbroker/repo_scanner.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Gitbroker
+  # Finds GitHub checkouts under the configured roots and reports them (DeviceRepository), so a card only offers
+  # agents where a checkout exists. Reads .git/config as a file; never runs git in scanned directories.
+  class RepoScanner
+    GITHUB_URL = %r{\A(?:https://github\.com/|git@github\.com:|ssh://git@github\.com/)([\w.-]+)/([\w.-]+?)(?:\.git)?/?\z}
+    SKIP = %w[node_modules vendor tmp log].freeze
+
+    def self.full_name_from(url)
+      match = GITHUB_URL.match(url.to_s.strip)
+      match && "#{match[1]}/#{match[2]}".downcase
+    end
+
+    def initialize(roots:, depth: 3, exclude: [])
+      @roots = roots
+      @depth = depth
+      @exclude = exclude.map { File.expand_path(_1) }
+    end
+
+    def scan
+      found = {}
+      @roots.each { |root| walk(File.expand_path(root), 0, found) if File.directory?(root) }
+      found.sort.map { |full_name, path| { "full_name" => full_name, "path" => path } }
+    end
+
+    private
+
+    def walk(dir, level, found)
+      return if @exclude.any? { |excluded| dir == excluded || dir.start_with?("#{excluded}/") }
+
+      if File.exist?(File.join(dir, ".git"))
+        remote_names(dir).each { |name| found[name] = dir if found[name].nil? || dir.length < found[name].length }
+        return
+      end
+      return if level >= @depth
+
+      Dir.children(dir).sort.each do |child|
+        next if child.start_with?(".") || SKIP.include?(child)
+
+        path = File.join(dir, child)
+        walk(path, level + 1, found) if File.directory?(path) && !File.symlink?(path)
+      end
+    rescue Errno::EACCES, Errno::ENOENT, Errno::ENOTDIR
+      nil
+    end
+
+    def remote_names(dir) = GitContext.remote_urls(dir).filter_map { |_name, url| self.class.full_name_from(url) }.uniq
+  end
+end