gitbroker 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e825e1f8def558d93779836b95723c78ac59115e75c364b4c1e0a0e1d9b6b7a1
-  data.tar.gz: 82223713f2753ca463bf44c662dfcf2b1c6eb5f0ba0f3d99814995a0e54f521f
+  metadata.gz: 227a743489c659dad707f6e11180988105a2ec34d89601a6ec61d62f5c4a8f53
+  data.tar.gz: 2ab80c483b24299e9c2776cc44fcda117e7fc5274069f1107f48e26c044190d0
 SHA512:
-  metadata.gz: aa00217897008aeefe8570ed5ced03eac40b9c04542fba6fea03e233ab0df0fa250783d00cc39a3e50ccf1c9b0bda3341e1f9e93d668bece0e41c37746b5a3bf
-  data.tar.gz: 7238f88f3a6413ea49feef55ef41324db9410821c6d7d9a756e839e7c9aa108ce17f27cc97a1fbbe73956c79ea452354d7c25e0650ba9008ebcb9223c3102d2f
+  metadata.gz: ac95b2ec94aca69fcd5cc0f78b0cc1f5541098158722c13825d3f32746ec3ecd2c0c2c0f339f3a405ad12cca055d11894ebaabb96e462836bf69d2a9a71fcd5f
+  data.tar.gz: f0507d54eeb1efefebc493b2edbade05da29e6a589ae0260ab79b3c6d61090ffdeb6dacf7019a379c0237160ac5331029f2bdb20f65ca0fc072d03009681f0bf

data/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 GitBroker
+Copyright (c) 2026 Yuri Sidorov
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/lib/gitbroker/cli.rb

@@ -16,6 +16,8 @@ module Gitbroker
         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 gitbroker`
+        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)
         install-service                     Run `gitbroker start` in the background (launchd / systemd --user), and let
                                             the website's "Start companion" button wake it (gitbroker:// handler)
         install-skill                       Install the gitbroker skills into ~/.claude/skills
@@ -30,8 +32,10 @@ module Gitbroker
       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)
+    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
@@ -50,6 +54,8 @@ module Gitbroker
       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
@@ -93,7 +99,12 @@ module Gitbroker
       raise Error, "This machine is not paired. Run `gitbroker login` first." unless config.paired?
 
       path = ServiceInstaller.new(home: @home, env: @env).install!
-      @out.puts "Installed and started #{path}. Run this again after upgrading the gem."
+      @out.puts "Installed and started #{path}."
+      if ServiceInstaller.pinned?
+        @out.puts "No RubyGems `gitbroker` wrapper was found, so it runs this version-pinned gem executable: run " \
+                  "`gitbroker 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
@@ -120,6 +131,27 @@ module Gitbroker
       @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 `gitbroker login` 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 gitbroker` 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
@@ -152,6 +184,14 @@ module Gitbroker
 
     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

data/lib/gitbroker/daemon.rb

@@ -38,7 +38,8 @@ module Gitbroker
     end
 
     def initialize(scanner:, client_factory:, task_runner_factory:, out: $stdout, sleeper: ->(seconds) { sleep(seconds) },
-                   clock: -> { Time.now }, spawner: ->(&block) { Thread.new(&block) }, relay: nil, process_scanner: nil, lifecycle: nil)
+                   clock: -> { Time.now }, spawner: ->(&block) { Thread.new(&block) }, relay: nil, process_scanner: nil, lifecycle: nil,
+                   maintenance: Maintenance.new)
       @scanner = scanner
       @client_factory = client_factory
       @task_runner = task_runner_factory.call(method(:report))
@@ -49,6 +50,7 @@ module Gitbroker
       @relay = relay
       @process_scanner = process_scanner
       @lifecycle = lifecycle
+      @maintenance = maintenance
       @repositories = []
       @running = Set.new
       @running_lock = Mutex.new
@@ -95,6 +97,8 @@ module Gitbroker
       client.on_subscribed do
         @backoff = 1
         rescan(client)
+        client.perform("hello", "version" => VERSION, "platform" => Gitbroker.platform,
+                                "service" => @lifecycle ? @lifecycle.service_installed? : false)
         @out.puts "Connected. #{@repositories.size} repositories reported."
       end
       client.on_tick do
@@ -118,7 +122,8 @@ module Gitbroker
       clean.each_slice(BATCH) { client.perform("observe", "events" => _1) }
     end
 
-    # The website's Restart / Stop buttons (Device#control!). Nothing else about the message is trusted or used.
+    # The website's Restart / Stop / Upgrade / Uninstall buttons (Device#control!). Only the action name is used, to pick
+    # one of these fixed behaviours; nothing from the message reaches a command.
     def control(action)
       return unless @lifecycle
 
@@ -134,9 +139,64 @@ module Gitbroker
 
         @respawn = true
         stop
+      when "upgrade" then upgrade
+      when "uninstall" then uninstall
       end
     end
 
+    # Never while a task runs: the restart would kill it. A deferred upgrade runs once, when the last task ends.
+    # Results name the control under "control", not "action": Action Cable's perform overwrites a data key "action" with
+    # the method name ("control_result").
+    def upgrade
+      return unless claim_upgrade
+
+      @out.puts "Upgrading (asked from GitBroker)."
+      @maintenance.upgrade!
+      report("control_result", "control" => "upgrade", "ok" => true, "error" => nil)
+      restart_into_new_version
+    rescue StandardError => e
+      @running_lock.synchronize { @upgrading = false } # the old companion keeps running; another request may retry
+      @out.puts "Upgrade failed: #{e.message}"
+      report("control_result", "control" => "upgrade", "ok" => false, "error" => e.message[0, 200])
+    end
+
+    # True when the upgrade should run now. With tasks running it is remembered instead; one already under way wins.
+    def claim_upgrade
+      @running_lock.synchronize do
+        if @upgrading
+          false
+        elsif @running.any?
+          @pending_upgrade = true
+          false
+        else
+          @pending_upgrade = false
+          @upgrading = true
+        end
+      end
+    end
+
+    # With a service the manager restarts us into the new gem (it may kill us mid-call); otherwise respawn after the loop.
+    def restart_into_new_version
+      @out.puts "Upgraded; restarting."
+      return if @lifecycle.restart_service
+
+      @respawn = true
+      stop
+    end
+
+    # Reports once the gem is gone (or failed to go), before removing the service: that step may end this process.
+    # Never respawns.
+    def uninstall
+      @running_lock.synchronize { @upgrading = true } # no task is claimed or started from here on
+      @out.puts "Uninstalling (asked from GitBroker)."
+      @maintenance.uninstall!(service: @lifecycle.service, url_handler: UrlHandlerInstaller.new) do |error|
+        report("control_result", "control" => "uninstall", "ok" => error.nil?, "error" => error && error[0, 200])
+      end
+      stop
+    end
+
+    def upgrading? = @running_lock.synchronize { @upgrading }
+
     def handle(client, message)
       return control(message["action"]) if message["type"] == "control"
 
@@ -144,14 +204,14 @@ module Gitbroker
       return unless id.is_a?(String)
 
       case message["type"]
-      when "task_available" then client.perform("claim", "task_id" => id)
+      when "task_available" then client.perform("claim", "task_id" => id) unless upgrading? # left to another device or the sweep
       when "cancel" then @task_runner.cancel(id)
       when "task" then start_task(id, message)
       end
     end
 
     def start_task(id, message)
-      return unless @running_lock.synchronize { @running.add?(id) }
+      return unless @running_lock.synchronize { !@upgrading && @running.add?(id) } # the upgrade's restart would kill it
 
       repositories = @repositories
       @spawner.call do
@@ -159,7 +219,8 @@ module Gitbroker
       rescue StandardError => e
         @out.puts "Task #{id} crashed: #{e.class}: #{e.message}"
       ensure
-        @running_lock.synchronize { @running.delete(id) }
+        upgrade_now = @running_lock.synchronize { @running.delete(id) && @pending_upgrade && @running.empty? }
+        upgrade if upgrade_now
       end
     end
   end

data/lib/gitbroker/hooks_installer.rb

@@ -16,9 +16,10 @@ module Gitbroker
 
     attr_reader :settings_path
 
-    def self.default(env: ENV, home: Dir.home)
+    # RubyGems' stable wrapper (ServiceInstaller.launcher): the hooks keep working after an upgrade's `gem cleanup`.
+    def self.default(env: ENV, home: Dir.home, exe: ServiceInstaller.launcher)
       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)}")
+          command_prefix: "#{Shellwords.escape(RbConfig.ruby)} #{Shellwords.escape(exe)}")
     end
 
     def initialize(settings_path:, command_prefix:, clock: -> { Time.now })

data/lib/gitbroker/lifecycle.rb

@@ -11,7 +11,7 @@ module Gitbroker
     PID_FILE = "daemon.pid"
     WAIT = 10
 
-    def initialize(dir:, home: Dir.home, service: ServiceInstaller.new(home:), runner: Runner.new, exe: ServiceInstaller::EXE,
+    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)
       @dir = dir
       @home = home
@@ -24,6 +24,8 @@ module Gitbroker
       @pid = pid
     end
 
+    attr_reader :service
+
     def pid_path = File.join(@dir, PID_FILE)
     def service_installed? = @service.installed?
     def log_path = File.join(@home, ".config", "gitbroker", "companion.log")

data/lib/gitbroker/maintenance.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module Gitbroker
+  # Upgrading and uninstalling the companion itself: fixed command sequences, nothing taken from the website's message.
+  class Maintenance
+    GEM_NAME = "gitbroker"
+
+    # `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")
+      Gitbroker.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:)
+      Gitbroker.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/gitbroker/run_script.rb

@@ -10,9 +10,9 @@ module Gitbroker
   # quoting never matters. When the agent exits, `gitbroker task-ended` tells GitBroker.
   class RunScript
     TASK_ID = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/
-    EXE = File.join(Gitbroker::ROOT, "exe", "gitbroker")
 
-    def initialize(state_dir:, ruby: RbConfig.ruby, exe: EXE)
+    # RubyGems' stable wrapper (ServiceInstaller.launcher): a terminal task may outlive an upgrade's `gem cleanup`.
+    def initialize(state_dir:, ruby: RbConfig.ruby, exe: ServiceInstaller.launcher)
       @state_dir = state_dir
       @ruby = ruby
       @exe = exe

data/lib/gitbroker/service_installer.rb

@@ -9,7 +9,24 @@ module Gitbroker
     LABEL = "broker.git.companion"
     EXE = File.join(Gitbroker::ROOT, "exe", "gitbroker")
 
-    def initialize(platform: Gitbroker.platform, home: Dir.home, ruby: RbConfig.ruby, exe: EXE, env: ENV, runner: Runner.new,
+    # What the service and the "Start companion" app run. RubyGems' own wrapper activates the newest installed gitbroker
+    # on every start, so a restart loads an upgraded gem and old versions can be removed. The gem's own exe is the
+    # fallback (and what a test passes), pinned to the version that ran `install-service`.
+    def self.launcher(bindir: launcher_bindirs)
+      Array(bindir).map { File.join(_1, "gitbroker") }.find { File.executable?(_1) } || EXE
+    end
+
+    # Where RubyGems puts the wrapper: the default bindir, the bindir of the install location this gem came from, and
+    # the per-user one (`gem install --user-install`).
+    def self.launcher_bindirs
+      spec = Gem.loaded_specs["gitbroker"]
+      [ Gem.bindir, (Gem.bindir(spec.base_dir) if spec), File.join(Gem.user_dir, "bin") ].compact.uniq
+    end
+
+    # True when the launcher is this version's own exe, which `gem cleanup` deletes once a newer version is installed.
+    def self.pinned?(launcher = self.launcher) = launcher == EXE
+
+    def initialize(platform: Gitbroker.platform, home: Dir.home, ruby: RbConfig.ruby, exe: ServiceInstaller.launcher, env: ENV, runner: Runner.new,
                    uid: Process.uid)
       @platform = platform
       @home = home
@@ -60,6 +77,23 @@ module Gitbroker
       end
     end
 
+    # Stops and removes the background service. False when none was installed. The file goes first on macOS: booting
+    # out the job ends the daemon when it is the one uninstalling. systemd needs the unit file to disable it, so a
+    # daemon uninstalling itself may leave a disabled, stopped unit behind.
+    def uninstall!
+      return false unless installed?
+
+      if @platform == "macos"
+        File.delete(launchd_path)
+        @runner.success?("launchctl", "bootout", target)
+      else
+        @runner.success?("systemctl", "--user", "disable", "--now", "gitbroker.service")
+        File.delete(systemd_path)
+        @runner.success?("systemctl", "--user", "daemon-reload")
+      end
+      true
+    end
+
     def plist
       arguments = [ @ruby, @exe, "start" ].map { "    <string>#{xml(_1)}</string>" }.join("\n")
       environment = { "PATH" => @env["PATH"].to_s, "SHELL" => @env["SHELL"] || "/bin/zsh", "LANG" => @env["LANG"] || "en_US.UTF-8" }

data/lib/gitbroker/url_handler_installer.rb

@@ -13,7 +13,7 @@ module Gitbroker
     APP_NAME = "GitBroker Companion"
     LSREGISTER = "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister"
 
-    def initialize(platform: Gitbroker.platform, home: Dir.home, ruby: RbConfig.ruby, exe: ServiceInstaller::EXE, runner: Runner.new)
+    def initialize(platform: Gitbroker.platform, home: Dir.home, ruby: RbConfig.ruby, exe: ServiceInstaller.launcher, runner: Runner.new)
       @platform = platform
       @home = home
       @ruby = ruby
@@ -23,10 +23,23 @@ module Gitbroker
 
     def install! = @platform == "macos" ? install_app! : install_desktop_entry!
 
+    # Removes the app bundle (unregistered from LaunchServices first) or the .desktop entry. False when absent.
+    def uninstall!
+      path = @platform == "macos" ? app_path : desktop_entry_path
+      return false unless File.exist?(path)
+
+      @runner.success?(LSREGISTER, "-u", path) if @platform == "macos"
+      FileUtils.rm_rf(path)
+      true
+    end
+
     private
 
+    def app_path = File.join(@home, "Applications", "#{APP_NAME}.app")
+    def desktop_entry_path = File.join(@home, ".local", "share", "applications", "gitbroker.desktop")
+
     def install_app!
-      app = File.join(@home, "Applications", "#{APP_NAME}.app")
+      app = app_path
       script = File.join(app, "Contents", "MacOS", "gitbroker-launch")
       FileUtils.mkdir_p(File.dirname(script))
       File.write(File.join(app, "Contents", "Info.plist"), info_plist)
@@ -69,7 +82,7 @@ module Gitbroker
     end
 
     def install_desktop_entry!
-      path = File.join(@home, ".local", "share", "applications", "gitbroker.desktop")
+      path = desktop_entry_path
       FileUtils.mkdir_p(File.dirname(path))
       File.write(path, <<~ENTRY)
         [Desktop Entry]

data/lib/gitbroker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Gitbroker
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end

data/lib/gitbroker.rb

@@ -10,6 +10,9 @@ module Gitbroker
 
   def self.platform = RUBY_PLATFORM.include?("darwin") ? "macos" : "linux"
 
+  # Loads every autoloaded constant. Called before `gem cleanup` removes the files of the running version.
+  def self.eager_load! = constants.each { const_get(_1) }
+
   autoload :Agents, File.expand_path("gitbroker/agents", __dir__)
   autoload :Api, File.expand_path("gitbroker/api", __dir__)
   autoload :CableClient, File.expand_path("gitbroker/cable_client", __dir__)
@@ -23,6 +26,7 @@ module Gitbroker
   autoload :HooksInstaller, File.expand_path("gitbroker/hooks_installer", __dir__)
   autoload :Lifecycle, File.expand_path("gitbroker/lifecycle", __dir__)
   autoload :Launcher, File.expand_path("gitbroker/launcher", __dir__)
+  autoload :Maintenance, File.expand_path("gitbroker/maintenance", __dir__)
   autoload :LocalRelay, File.expand_path("gitbroker/local_relay", __dir__)
   autoload :Login, File.expand_path("gitbroker/login", __dir__)
   autoload :Neutralizer, File.expand_path("gitbroker/neutralizer", __dir__)

data/plugin/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "gitbroker",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Skills for working on GitBroker agent tasks: the gitbroker MCP tools, write rules and report_task."
 }

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: gitbroker
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
-- GitBroker
+- Yuri Sidorov (@newstler)
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
@@ -52,6 +52,7 @@ files:
 - lib/gitbroker/lifecycle.rb
 - lib/gitbroker/local_relay.rb
 - lib/gitbroker/login.rb
+- lib/gitbroker/maintenance.rb
 - lib/gitbroker/neutralizer.rb
 - lib/gitbroker/process_scanner.rb
 - lib/gitbroker/repo_scanner.rb