diffbroker 0.9.0

data/lib/diffbroker/launcher.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "shellwords"
+require "yaml"
+require "fileutils"
+
+module Diffbroker
+  # 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: Diffbroker.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", "diffbroker", "-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 = "diffbroker-#{title}.yaml"
+      config = { "name" => "Diff Broker #{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/diffbroker/lifecycle.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "rbconfig"
+
+module Diffbroker
+  # Stopping, restarting and spawning the companion on this machine: used by `diffbroker 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.launcher,
+                   ruby: RbConfig.ruby, spawner: nil, sleeper: ->(seconds) { sleep(seconds) }, pid: Process.pid, env: ENV, server: nil)
+      @dir = dir
+      @home = home
+      @service = service
+      @runner = runner
+      @exe = exe
+      @ruby = ruby
+      @spawner = spawner || method(:spawn_process)
+      @sleeper = sleeper
+      @pid = pid
+      @env = env
+      @server = server
+    end
+
+    attr_reader :service
+
+    def pid_path = File.join(@dir, PID_FILE)
+    def service_installed? = @service.installed?
+    def log_path = File.join(@home, ".config", "diffbroker", "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
+
+    # True only for the daemon the service manager started (launchd sets XPC_SERVICE_NAME to the job's label, systemd sets
+    # INVOCATION_ID). A daemon started by hand (`diffbroker start --server http://localhost:3000`) is not the service's:
+    # asking the manager to restart or stop "the service" would act on a different process (the one pointed at the
+    # default server) and leave this one running its old code for ever.
+    def service_process? = @env["XPC_SERVICE_NAME"] == ServiceInstaller::LABEL || @env.key?("INVOCATION_ID")
+
+    # Used by the daemon itself: false when this is not the service's daemon, no service is installed or the manager refused.
+    def stop_service = service_process? && @service.installed? && @service.stop!
+    def restart_service = service_process? && @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 diffbroker 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?("diffbroker") ? 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
+
+    # The respawned daemon talks to the server this one did (a daemon started by hand against a local server must not come
+    # back pointed at the default one).
+    def spawn_process(argv, log)
+      env = @server ? { "DIFFBROKER_SERVER" => @server } : {}
+      Process.detach(Process.spawn(env, *argv, in: File::NULL, out: [ log, "a" ], err: [ log, "a" ], pgroup: true))
+    end
+  end
+end

data/lib/diffbroker/local_relay.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "socket"
+require "json"
+require "io/wait"
+require "fileutils"
+
+module Diffbroker
+  # Unix socket between `diffbroker 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 diffbroker 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/diffbroker/login.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Diffbroker
+  # RFC 8628-style device-code pairing against POST /device_authorizations (spec §4.1).
+  class Login
+    def self.open_browser(url)
+      system(Diffbroker.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: Diffbroker.platform })
+      code = auth.fetch("user_code")
+      uri = auth.fetch("verification_uri")
+      # No pre-filled link: nothing in a URL may select a code, the user types it on the plain page. The companion never
+      # touches the clipboard.
+      @out.puts "Pairing #{@name} with Diff Broker."
+      @out.puts
+      @out.puts "  Your code: #{code}"
+      @out.puts
+      @out.puts "Enter it at #{uri}, press Pair, then check the device details and press Approve."
+      @out.puts "Only enter a code you see here, in your own terminal."
+      @opener.call(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 `diffbroker start` 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 `diffbroker start` 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."
+        return token["device_id"]
+      end
+    end
+  end
+end

data/lib/diffbroker/maintenance.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module Diffbroker
+  # Upgrading and uninstalling the companion itself: fixed command sequences, nothing taken from the website's message.
+  class Maintenance
+    GEM_NAME = "diffbroker"
+
+    # `hooks`: the user's Claude Code hooks (HooksInstaller). `launcher`: what the service and the hooks run.
+    def initialize(runner: Runner.new, bindir: RbConfig::CONFIG["bindir"], hooks: HooksInstaller.default,
+                   launcher: ServiceInstaller.launcher)
+      @runner = runner
+      @gem = File.join(bindir, "gem")
+      @hooks = hooks
+      @launcher = launcher
+    end
+
+    # Installs the newest release, then removes the old versions. The running process loads all its code first: cleanup
+    # deletes the files of the version it runs. Hooks written by an older version name its versioned exe, so they are
+    # rewritten to the launcher first. With no RubyGems wrapper the service runs this version's own exe, so nothing is
+    # cleaned up. Raises Error (with gem's output) when the install fails.
+    def upgrade!
+      @runner.run!(@gem, "install", GEM_NAME, "--no-document")
+      Diffbroker.eager_load!
+      refresh_hooks
+      @runner.success?(@gem, "cleanup", GEM_NAME) unless ServiceInstaller.pinned?(@launcher) # a failure is harmless
+      true
+    end
+
+    # True when the gem was uninstalled. The service goes last: stopping it ends the daemon when the daemon is the one
+    # uninstalling, so the gem's failure text (nil on success) is yielded before that step, for a report that gets out.
+    def uninstall!(service:, url_handler:)
+      Diffbroker.eager_load!
+      remove_hooks # they would run a missing file on every Claude Code event
+      error = uninstall_gem
+      url_handler.uninstall!
+      yield error if block_given?
+      service.uninstall!
+      error.nil?
+    end
+
+    private
+
+    # A broken settings file never blocks an upgrade or an uninstall.
+    def refresh_hooks
+      @hooks.install! if @hooks.installed?
+    rescue Error
+      nil
+    end
+
+    def remove_hooks
+      @hooks.uninstall!
+    rescue Error
+      nil
+    end
+
+    def uninstall_gem
+      @runner.run!(@gem, "uninstall", GEM_NAME, "--all", "--executables", "--ignore-dependencies")
+      nil
+    rescue Error => e
+      e.message
+    end
+  end
+end

data/lib/diffbroker/neutralizer.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Diffbroker
+  # 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:, remote: "origin")
+      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/diffbroker/base-#{number}"
+      @runner.git(repo_path, "fetch", "--quiet", remote, "+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/diffbroker/process_scanner.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Diffbroker
+  # 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: Diffbroker.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
+
+    # pid => cwd for the given pids (lsof on macOS, /proc on Linux); a pid that vanished is left out.
+    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
+
+    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 proc_cwd(pid)
+      File.readlink(File.join(@proc_root, pid.to_s, "cwd"))
+    rescue SystemCallError
+      nil
+    end
+  end
+end