diffbroker 0.9.0

data/lib/diffbroker/cli.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "openssl"
+require "optparse"
+require "rbconfig"
+require "socket"
+
+module Diffbroker
+  class CLI
+    HELP = <<~TEXT
+      Usage: diffbroker <command> [options]
+
+      Commands:
+        start [--server URL] [--name NAME]  Set this machine up and keep it connected: pairs it (paste the code
+                                            it prints at diff.broker/devices), installs the background service and the
+                                            "Start companion" button, then runs your agent when you ask from a PR card.
+                                            Run it again any time; it only does what is still missing.
+        launch                              Start the companion in the background if it is not running
+        stop                                Stop the companion (and its background service, so it stays stopped)
+        restart                             Restart the companion, e.g. after `gem update diffbroker`
+        upgrade                             Install the newest gem, remove old versions, restart the companion
+        uninstall                           Remove the service, the start link, the Claude Code hooks and the gem (keeps your pairing)
+        login [--server URL] [--name NAME]  Only pair this machine (`start` does this when needed)
+        install-service                     Only (re)install the background service (launchd / systemd --user) and the
+                                            "Start companion" handler (`start` does this when needed)
+        install-skill                       Install the diffbroker skills into ~/.claude/skills
+        status                              Show pairing, configuration and the repositories found
+        clean                               Remove finished agent worktrees and stop their leftover processes (keeps worktrees with uncommitted work)
+        install-hooks [--yes]               Show your own Claude Code sessions on your cards (asks first)
+        uninstall-hooks                     Remove those hooks
+        help                                Show this help
+
+      Config: ~/.config/diffbroker/config.yml (server, roots, scan_depth, terminal, worktree_root, agent,
+              claude_args, codex_args). Your agent runs as you, with your own login and credentials.
+      Agent activity is visible only to you; only status is sent, never prompts, file contents or tool input.
+    TEXT
+
+    def initialize(argv, out: $stdout, err: $stderr, env: ENV, home: Dir.home, input: $stdin, maintenance: nil, lifecycle: nil)
+      @argv = argv.dup
+      @maintenance = maintenance
+      @lifecycle = lifecycle
+      @out = out
+      @err = err
+      @env = env
+      @home = home
+      @input = input
+    end
+
+    def run
+      command = @argv.shift || "help"
+      return task_ended if command == "task-ended"
+      return publish_branch if command == "publish-branch"
+      return hook if command == "hook"
+
+      case command
+      when "login" then login
+      when "start" then start
+      when "launch" then launch
+      when "stop" then stop
+      when "restart" then restart
+      when "upgrade" then upgrade
+      when "uninstall" then uninstall
+      when "install-service" then install_service
+      when "install-skill" then install_skill
+      when "status" then status
+      when "clean" then clean
+      when "install-hooks" then install_hooks
+      when "uninstall-hooks" then uninstall_hooks
+      when "help", "-h", "--help" then @out.puts(HELP)
+      else
+        @err.puts "Unknown command: #{command}"
+        @err.puts HELP
+        return 1
+      end
+      0
+    rescue Error, OptionParser::ParseError => e
+      @err.puts "diffbroker: #{e.message}"
+      1
+    end
+
+    private
+
+    def config = @config ||= Config.load(dir: Config.default_dir(@env), env: @env, home: @home)
+
+    def login
+      options = {}
+      OptionParser.new do |parser|
+        parser.on("--server URL") { options[:server] = _1 }
+        parser.on("--name NAME") { options[:name] = _1 }
+      end.parse!(@argv)
+      @config = config.save!("server" => options[:server]) if options[:server]
+      Login.new(config:, out: @out, name: options[:name] || Socket.gethostname).run
+    end
+
+    # In a terminal: whatever is still missing (pairing, the background service) is set up, then the companion is left
+    # running in the background. Without a terminal (the service, `diffbroker launch`) or with --foreground: the daemon
+    # itself, in this process.
+    def start
+      options = {}
+      OptionParser.new do |parser|
+        parser.on("--server URL") { options[:server] = _1 }
+        parser.on("--name NAME") { options[:name] = _1 }
+        parser.on("--foreground") { options[:foreground] = true }
+      end.parse!(@argv)
+      foreground = options[:foreground] || !@input.tty?
+      if options[:server]
+        # Setting a machine up remembers its server (the background service must use it too). A daemon run by hand only
+        # uses it for this run: it must not rewrite the settings the service reads.
+        @config = foreground ? Config.load(dir: Config.default_dir(@env), env: @env.merge("DIFFBROKER_SERVER" => options[:server]), home: @home) : config.save!("server" => options[:server])
+      end
+
+      return run_daemon if foreground
+      return set_up_separate_instance(options[:name] || Socket.gethostname) if separate_instance?
+
+      set_up(options[:name] || Socket.gethostname)
+    end
+
+    # A DIFFBROKER_CONFIG_DIR that is not the default is another companion (say, one for a local dev server). The background
+    # service belongs to the default one, so this one is paired and then kept in this window; it never touches the service.
+    def separate_instance?
+      custom = @env["DIFFBROKER_CONFIG_DIR"]
+      custom && File.expand_path(custom) != File.expand_path(Config.default_dir(@env.reject { |key, _| key == "DIFFBROKER_CONFIG_DIR" }))
+    end
+
+    def set_up_separate_instance(name)
+      Login.new(config:, out: @out, name:).run unless config.paired?
+      @out.puts "This companion uses its own settings (#{config.dir}), so the background service is left alone. Keeping it in this " \
+                "window, connected to #{config.server}; press Ctrl-C to stop it."
+      run_daemon
+    end
+
+    def run_daemon
+      raise Error, "This machine is not paired. Run `diffbroker start` in a terminal to pair it." unless config.paired?
+
+      @out.puts "Diff Broker companion #{VERSION} → #{config.server} (agent: #{config.agent}, terminal: #{config.terminal})"
+      Daemon.build(config, out: @out).run
+    rescue Daemon::Rejected
+      # The pairing is dead. Forget it and remove the service, so nothing restarts a daemon that can never connect.
+      config.clear_credentials!
+      ServiceInstaller.new(home: @home, env: @env).uninstall!
+      raise
+    end
+
+    def set_up(name)
+      forget_dead_pairing if config.paired? && pairing_rejected?
+      Login.new(config:, out: @out, name:).run unless config.paired?
+      install_background_service
+      @out.puts "Diff Broker is running in the background. Open #{config.server} to see it connected."
+    rescue Error => e
+      raise unless service_unavailable?(e)
+
+      @out.puts "No background service is available here (#{e.message}). Keeping the companion in this window; run " \
+                "`diffbroker start` again after a restart. Press Ctrl-C to stop it."
+      run_daemon
+    end
+
+    # True only when the server answered "unauthorized". An unreachable server proves nothing, so the pairing is kept.
+    def pairing_rejected?
+      Api.new(server: config.server, token: config.device_token).get("/device/ping")
+      false
+    rescue Api::HttpError => e
+      e.status == 401
+    rescue SystemCallError, IOError, SocketError, Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError
+      false
+    end
+
+    def forget_dead_pairing
+      @out.puts "Diff Broker no longer knows this machine, so it needs pairing again."
+      config.clear_credentials!
+      ServiceInstaller.new(home: @home, env: @env).uninstall!
+    end
+
+    # Installs what is missing and starts it. A service that is already installed is only started (installing again
+    # would restart a daemon that may be running a task).
+    def install_background_service
+      service = ServiceInstaller.new(home: @home, env: @env)
+      return lifecycle.launch if service.installed?
+
+      install_service
+    end
+
+    def service_unavailable?(error) = error.message.include?("not found on PATH") || error.message.include?("systemctl")
+
+    def install_service
+      raise Error, "This machine is not paired. Run `diffbroker start` first." unless config.paired?
+
+      path = ServiceInstaller.new(home: @home, env: @env).install!
+      @out.puts "Installed and started #{path}."
+      if ServiceInstaller.pinned?
+        @out.puts "No RubyGems `diffbroker` wrapper was found, so it runs this version-pinned gem executable: run " \
+                  "`diffbroker install-service` again after upgrading the gem."
+      end
+      refresh_hooks
+      handler = UrlHandlerInstaller.new(home: @home).install!
+      @out.puts "Registered #{handler} so the website's \"Start companion\" button can wake it."
+    end
+
+    # The target of the website's diffbroker://start link and of `diffbroker launch` by hand: start the background
+    # service, or the daemon itself when none is installed. Safe to run when it is already running.
+    def launch
+      raise Error, "This machine is not paired. Run `diffbroker start` first." unless config.paired?
+      lifecycle.launch
+    end
+
+    def lifecycle = @lifecycle ||= Lifecycle.new(dir: config.dir, home: @home, service: ServiceInstaller.new(home: @home, env: @env))
+
+    # Works on this machine only. With a background service installed it is stopped through launchd / systemd, so it
+    # stays stopped until `diffbroker launch` (or the website's "Start companion" button).
+    def stop
+      @out.puts(lifecycle.stop ? "Stopped the companion." : "The companion is not running.")
+    end
+
+    def restart
+      raise Error, "This machine is not paired. Run `diffbroker start` first." unless config.paired?
+
+      lifecycle.restart
+      @out.puts "Restarting the companion."
+    end
+
+    def maintenance = @maintenance ||= Maintenance.new(hooks: hooks_installer)
+
+    # The restart runs this (old) process's code, which only asks the service manager or spawns RubyGems' wrapper, so
+    # the companion comes back on the new version. An unpaired machine has no companion to restart.
+    def upgrade
+      maintenance.upgrade!
+      return @out.puts("Upgraded. Run `diffbroker start` to pair this machine.") unless config.paired?
+
+      lifecycle.restart
+      @out.puts "Upgraded. Restarting the companion."
+    end
+
+    def uninstall
+      lifecycle.stop # a companion started by hand too, not only the service
+      error = nil
+      removed = maintenance.uninstall!(service: ServiceInstaller.new(home: @home, env: @env), url_handler: UrlHandlerInstaller.new(home: @home)) { error = _1 }
+      raise Error, "Removed the service, the start link and the hooks, but `gem uninstall diffbroker` failed: #{error}" unless removed
+
+      @out.puts "Uninstalled the service, the start link, the Claude Code hooks and the gem. Your pairing in #{config.dir} is kept."
+    end
+
+    def install_skill
+      SkillInstaller.new(home: @home, env: @env).install!.each { @out.puts "Installed the #{File.basename(_1)} skill to #{_1}." }
+    end
+
+    def status
+      @out.puts "Diff Broker companion #{VERSION}"
+      @out.puts "Server:     #{config.server}"
+      @out.puts "Paired:     #{config.paired? ? "yes (device #{config.device_id})" : "no (run `diffbroker start`)"}"
+      @out.puts "Agent:      #{config.agent}"
+      @out.puts "Terminal:   #{config.terminal}"
+      @out.puts "Hooks:      #{hooks_installer.installed? ? "installed" : "not installed (diffbroker install-hooks)"}"
+      @out.puts "Roots:      #{config.roots.join(", ")} (plus the projects Claude Code and Codex know)"
+      @out.puts "Worktrees:  #{config.worktree_root}"
+      @out.puts "Task worktrees: #{Worktree.new(root: config.worktree_root).list.size} (running or kept; `diffbroker clean` removes finished ones)"
+      repositories = config.repo_scanner.scan
+      @out.puts "Repositories found: #{repositories.size}"
+      repositories.each { @out.puts "  #{_1["full_name"]}  #{_1["path"]}" }
+    end
+
+    # `git worktree remove` without --force refuses a worktree with modified or untracked files, so work is never lost.
+    def clean
+      worktree = Worktree.new(root: config.worktree_root)
+      stopped = Reaper.new(root: config.worktree_root).sweep!
+      @out.puts "Stopped #{stopped} leftover process#{"es" unless stopped == 1} (rubocop --server and the like)." if stopped.positive?
+      worktree.list.each do |dir|
+        git_dir = GitContext.git_dir(dir)
+        repo_path = git_dir && File.dirname(GitContext.common_dir(git_dir))
+        removed = repo_path && File.directory?(repo_path) && worktree.remove!(dir, repo_path:)
+        @out.puts(removed ? "Removed #{dir}" : "Kept #{dir} (uncommitted work)")
+      end
+    end
+
+    def hooks_installer = HooksInstaller.default(env: @env, home: @home)
+
+    # Hooks written by an older version name its versioned exe; point them at the current launcher.
+    def refresh_hooks
+      installer = hooks_installer
+      installer.install! if installer.installed?
+    rescue Error
+      nil
+    end
+
+    # Called by Claude Code on every hook event: silent, always exit 0.
+    def hook
+      Hook.new(event: @argv.shift, input: @input, socket_path: File.join(Config.default_dir(@env), "daemon.sock"), env: @env).run
+      0
+    rescue StandardError
+      0
+    end
+
+    def install_hooks
+      yes = @argv.delete("--yes")
+      installer = hooks_installer
+      @out.puts "This adds Claude Code command hooks (#{HooksInstaller::EVENTS.join(", ")}) to #{installer.settings_path}."
+      @out.puts "Each runs `diffbroker hook <event>`, which tells your running companion the session id, repository, branch " \
+                "and head SHA. It never sends prompts, file contents or tool input, and only you see the result."
+      unless yes
+        @out.print "Add the hooks? [y/N] "
+        return @out.puts("Nothing changed.") unless %w[y yes].include?(@input.gets.to_s.strip.downcase)
+      end
+      backup = installer.install!
+      @out.puts "Hooks installed#{" (previous settings saved to #{backup})" if backup}. New Claude Code sessions pick them up."
+    end
+
+    def uninstall_hooks
+      if hooks_installer.installed? || File.exist?(hooks_installer.settings_path)
+        backup = hooks_installer.uninstall!
+        @out.puts(backup ? "Hooks removed (previous settings saved to #{backup})." : "No Diff Broker hooks found; nothing changed.")
+      else
+        @out.puts "No Claude Code settings file; nothing to remove."
+      end
+    end
+
+    # Called by the terminal run script after an update_branch agent exited successfully (not listed in the help: the
+    # companion's own script is the only caller): pushes the finished rebase (BranchPublisher). Exit 1 when it could not.
+    def publish_branch
+      options = {}
+      OptionParser.new do |parser|
+        parser.on("--dir DIR") { options[:dir] = _1 }
+        parser.on("--head-ref REF") { options[:head_ref] = _1 }
+        parser.on("--expected SHA") { options[:expected_sha] = _1 }
+        parser.on("--base REF") { options[:base_ref] = _1 }
+        parser.on("--remote NAME") { options[:remote] = _1 }
+      end.parse!(@argv)
+      result = BranchPublisher.new(**options).publish!
+      @out.puts result.message
+      result.failed? ? 1 : 0
+    rescue ArgumentError => e
+      @err.puts "diffbroker: #{e.message}"
+      1
+    end
+
+    # Called by the terminal run script after the agent exits: silent, always exit 0.
+    def task_ended
+      id = @env["DIFFBROKER_TASK_ID"].to_s
+      token = @env["DIFFBROKER_TASK_TOKEN"].to_s
+      return 0 if id.empty? || token.empty?
+
+      Api.new(server: @env["DIFFBROKER_SERVER"] || config.server, token:)
+         .post("/agent_tasks/#{id}/events", { hook_event_name: "TaskEnded", exit_status: @argv.first.to_s })
+      0
+    rescue StandardError # never break the user's terminal session over a status report
+      0
+    end
+  end
+end

data/lib/diffbroker/config.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+
+module Diffbroker
+  # ~/.config/diffbroker/config.yml (settings) and credentials.yml (0600, device token). Spec §4.1: roots, terminal,
+  # worktree location, preferred agent, and the agents' command-line args for autonomous runs (spec §4.2 step 5).
+  class Config
+    TERMINALS = %w[terminal iterm2 ghostty warp tmux].freeze
+    AGENTS = %w[claude codex].freeze
+    DEFAULT_SERVER = "https://diff.broker"
+    DEFAULT_CLAUDE_ARGS = %w[--permission-mode auto --permission-prompts none].freeze
+    DEFAULT_CODEX_ARGS = %w[--sandbox workspace-write -c sandbox_workspace_write.network_access=true].freeze
+    # Diff Broker sets these itself for every run; user args may not override them.
+    # Where people usually keep code; the ones that exist are always scanned (with `roots` and the agents' project lists).
+    COMMON_ROOTS = %w[~/Code ~/code ~/Projects ~/projects ~/Developer ~/dev ~/src ~/repos ~/workspace ~/work ~/git ~/github ~/Sites].freeze
+    RESERVED_ARGS = %w[-p --print --output-format --mcp-config --strict-mcp-config --plugin-dir --json].freeze
+
+    attr_reader :dir, :data, :home
+
+    def self.default_dir(env = ENV)
+      env["DIFFBROKER_CONFIG_DIR"] || File.join(env["XDG_CONFIG_HOME"] || File.join(Dir.home, ".config"), "diffbroker")
+    end
+
+    def self.common_roots(home = Dir.home)
+      COMMON_ROOTS.map { File.expand_path(_1.sub("~", home)) }.select { File.directory?(_1) }.uniq { _1.downcase }
+    end
+
+    MAX_DEVICE_ROOTS = 20
+
+    # The folders the user added in Diff Broker (a "roots" message from the server). The server is not trusted with more
+    # than a list of existing-looking absolute folders: no home folder, no "/", a bounded count.
+    def self.clean_device_roots(list, home: Dir.home)
+      home = File.expand_path(home)
+      Array(list).first(MAX_DEVICE_ROOTS * 2).filter_map { |entry|
+        next unless entry.is_a?(String) && entry.length <= 500 && !entry.include?("\0")
+
+        entry = entry.strip
+        next unless entry.start_with?("/", "~/")
+
+        path = File.expand_path(entry.sub(/\A~/, home))
+        path unless path == home || path == "/"
+      }.uniq.first(MAX_DEVICE_ROOTS)
+    end
+
+    def self.load(dir: default_dir, env: ENV, platform: Diffbroker.platform, home: Dir.home)
+      path = File.join(dir, "config.yml")
+      data = File.exist?(path) ? YAML.safe_load_file(path) || {} : {}
+      new(dir:, data:, env:, platform:, home:)
+    end
+
+    def initialize(dir:, data: {}, env: ENV, platform: Diffbroker.platform, home: Dir.home)
+      @dir = dir
+      @home = home
+      @data = data.to_h.transform_keys(&:to_s)
+      @env = env
+      @platform = platform
+      validate!
+    end
+
+    def server = (@env["DIFFBROKER_SERVER"] || data["server"] || DEFAULT_SERVER).to_s.chomp("/")
+    def cable_url = "#{server.sub(/\Ahttp/, "ws")}/cable"
+    # `roots` in config.yml and the folders added in Diff Broker (`device_roots`) add to the usual folders; the checkouts Claude Code and Codex know come in through `repo_scanner`.
+    def device_roots = self.class.clean_device_roots(data["device_roots"], home:)
+    def ignored_roots = self.class.clean_device_roots(data["ignored_roots"], home:)
+    def roots = (self.class.common_roots(home) + Array(data["roots"]).map { File.expand_path(_1.to_s.sub(/\A~/, home)) } + device_roots).uniq
+    # Folders the user removed in Diff Broker (`ignored_roots`) are skipped everywhere except inside a folder they added.
+    def repo_scanner
+      RepoScanner.new(roots: roots - device_roots, explicit_roots: device_roots, depth: scan_depth, exclude: [ worktree_root ],
+                      ignored: ignored_roots, hints: AgentProjects.paths(home:), home:)
+    end
+    def scan_depth = Integer(data["scan_depth"] || 3)
+    def terminal = (data["terminal"] || (@platform == "macos" ? "terminal" : "tmux")).to_s
+    def worktree_root = File.expand_path(data["worktree_root"] || File.join(home, ".local/share/diffbroker/worktrees"))
+    def state_dir = File.expand_path(data["state_dir"] || "~/.local/state/diffbroker")
+    def agent = (data["agent"] || "claude").to_s
+    def claude_command = (data["claude_command"] || "claude").to_s
+    def codex_command = (data["codex_command"] || "codex").to_s
+    def claude_args = data.key?("claude_args") ? data["claude_args"] : DEFAULT_CLAUDE_ARGS
+    def codex_args = data.key?("codex_args") ? data["codex_args"] : DEFAULT_CODEX_ARGS
+
+    def credentials_path = File.join(dir, "credentials.yml")
+    def device_token = credentials["device_token"]
+    def device_id = credentials["device_id"]
+    def paired? = !device_token.to_s.empty?
+
+    def save!(updates)
+      merged = data.merge(updates.transform_keys(&:to_s)).compact
+      FileUtils.mkdir_p(dir, mode: 0o700)
+      File.write(File.join(dir, "config.yml"), merged.to_yaml)
+      self.class.new(dir:, data: merged, env: @env, platform: @platform, home:)
+    end
+
+    def save_credentials!(device_token:, device_id:)
+      FileUtils.mkdir_p(dir, mode: 0o700)
+      File.write(credentials_path, { "device_token" => device_token, "device_id" => device_id, "server" => server }.to_yaml, perm: 0o600)
+      File.chmod(0o600, credentials_path)
+      @credentials = nil
+    end
+
+    # Forgets the pairing (the server no longer knows this device); the next `diffbroker start` pairs again.
+    def clear_credentials!
+      FileUtils.rm_f(credentials_path)
+      @credentials = nil
+    end
+
+    private
+
+    def credentials
+      @credentials ||= File.exist?(credentials_path) ? YAML.safe_load_file(credentials_path) || {} : {}
+    end
+
+    def validate!
+      raise Error, "Unknown terminal #{terminal.inspect}. Use one of: #{TERMINALS.join(", ")}" unless TERMINALS.include?(terminal)
+      raise Error, "Unknown agent #{agent.inspect}. Use one of: #{AGENTS.join(", ")}" unless AGENTS.include?(agent)
+
+      { "claude_args" => claude_args, "codex_args" => codex_args }.each do |key, args|
+        raise Error, "#{key} must be a list of strings" unless args.is_a?(Array) && args.all?(String)
+
+        reserved = args.map { _1.split("=").first } & RESERVED_ARGS
+        raise Error, "#{key} may not set #{reserved.join(", ")}; Diff Broker sets those itself" if reserved.any?
+      end
+    end
+  end
+end