brunch 0.9.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f7a05f3aae716ba9e82f616156c85380fad4437a5d0d440056a834999830fc6
-  data.tar.gz: dccd1027c1fb0a185807427cfe0ffbe06bc94362f656de08a064f52786c39ee2
+  metadata.gz: bfbfbc36f9114715c3b656aeeb831010e8e75e1ccc15d8c7229813b4489ceac6
+  data.tar.gz: 6a98d0331e7d758bacafad88344dd92a0a105b60c06ead342d35fb928e36cc0f
 SHA512:
-  metadata.gz: 550ae4c541eabe5196634628561c094e28039a578ccbb795c97ee41bb67b20fd48a58d4742bd685b877da57654784daa6a57004697422ad5b15f633199e9dc33
-  data.tar.gz: b6e4d92569d518d6ba19a8eb2b326996d0351a00cae53a03e4eecd23f0653a3cf5a6247a0db199b34050a47c49d8434e3ff6148860136dc99856fe8616f97ddc
+  metadata.gz: 64bbfe38e607cf1cf8cc1e9ce042e104653a4ac0958fdeca87ff6e40e4febf0f09e287d9c55f6cb7ce75c17a3062ad6edb1cd159f18407d3a52415192360c52b
+  data.tar.gz: ea493ddaa2e3431665a0a0a0d1c42f99a3013c9ab5ccafc98b170a98dfddd20188a7bd53dc6384f99a1469a5aba1b52298b1edd9881287e4d8c3365d246719c6

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.1.0 - 2026-10-16
+
+- Add opt-in `ports: auto` for Docker Compose and Podman Compose. Brunch now
+  renders a private Compose configuration and assigns every published host port
+  independently for each worktree, without modifying the repository file.
+- Add `brunch ports` and `brunch port SERVICE CONTAINER_PORT` for discovering
+  the complete set of assigned host ports.
+
+## 1.0.0 - 2026-10-16
+
+- Recover automatically when a stopped Compose environment cannot resume: Brunch
+  recreates the failed environment instead of leaving its worktree unavailable.
+- Correctly reconcile forced branch renames such as `git branch -M source target`
+  when the destination already has an environment.
+- Keep the 100% line and branch coverage gate for the regular test suite while
+  allowing manager integration jobs to report functional failures directly.
+- Clarify the lifecycle of stopped Compose containers, Rails PID files, forced
+  branch renames, and `brunch cleanup`.
+
 ## 0.9.2 - 2026-10-05
 
 - Settle branch deletions automatically after the Git process exits, preserving

data/README.md

@@ -96,6 +96,44 @@ preferred_port: 4000
 
 Port assignments are persisted per worktree in `.git/brunch/state.json`.
 
+### Existing Compose projects with several ports
+
+By default Brunch manages the `BRUNCH_PORT` variable shown above. To run an
+existing Compose project that publishes several fixed host ports, opt in with:
+
+```yaml
+ports: auto
+```
+
+Brunch renders the current Compose configuration, reserves every published
+host port, and writes a private generated configuration under `.git/brunch/`.
+It never changes the repository's `compose.yaml`. The first worktree keeps the
+declared ports whenever they are free; additional worktrees receive free ports
+for every published service port.
+
+For example, this requires no variables in the Compose file:
+
+```yaml
+services:
+  web:
+    ports:
+      - "3000:3000"
+      - "5173:5173"
+  mail:
+    ports:
+      - "8025:8025"
+```
+
+`brunch ports` displays all assigned mappings. Query one mapping with:
+
+```bash
+brunch port web 3000
+```
+
+Only `ports:` entries that publish a host port are managed; internal service
+ports and `expose:` remain unchanged. `BRUNCH_PORT` continues to contain the
+first published port for compatibility with existing scripts.
+
 ## Getting started
 
 Commit `brunch.yml` and the application configuration first. The repository must contain at least one commit.
@@ -140,6 +178,15 @@ With Compose, each branch keeps its own Compose project and named volumes, so pe
 Returning to a previously activated branch starts its stopped containers again,
 preserving files written inside them. The branch keeps the same host port.
 
+If a resumed Compose application exits immediately, Brunch recreates that
+environment automatically. This recovers the worktree but discards files kept
+only in the container's writable layer; named volumes remain intact.
+
+Applications that write a PID file inside the container should remove it before
+starting. For example, a Rails Compose command can begin with
+`rm -f /tmp/rails-server.pid &&`. A stopped container keeps its writable layer,
+including a stale PID file, until it is recreated.
+
 To manually start the environment after `brunch stop`:
 
 ```bash
@@ -176,12 +223,12 @@ Then:
 cd ../feature-a
 
 brunch port
-brunch list
+brunch ports
 ```
 
 `brunch port` prints the current worktree's port.
 
-`brunch list` groups the current and previously activated branches under each
+`brunch ports` groups the current and previously activated branches under each
 worktree. Stopped branches appear in gray and retain their worktree's port for
 the next activation.
 
@@ -194,6 +241,10 @@ brunch watch
 
 Switching branches inside one worktree does not affect environments running in other worktrees.
 
+For reliable automatic handling of forced branch renames such as
+`git branch -M source target`, use a Git version supported by `ghe doctor` and
+run `brunch install` after upgrading git-hooks-ext.
+
 If you create a worktree with plain Git:
 
 ```bash
@@ -214,6 +265,9 @@ brunch cleanup
 ```
 
 Brunch never deletes the worktree source directory.
+It removes environments for worktrees that Git no longer reports; it does not
+act as a general-purpose command for deleting the current worktree's stopped
+containers or volumes.
 
 ## Managers
 

data/lib/brunch/cli.rb

@@ -10,7 +10,7 @@ module Brunch
     include WorktreeMode
 
     PORT_RANGE = (1024..49_151)
-    CONFIGURATION_KEYS = %w[manager compose_file command commands preferred_port].freeze
+    CONFIGURATION_KEYS = %w[manager compose_file command commands preferred_port ports].freeze
     COMMAND_KEYS = %w[create start stop remove status health logs].freeze
 
     class ConfigurationError < StandardError; end
@@ -90,7 +90,8 @@ module Brunch
       path = File.join(root, "brunch.yml")
       configured = File.file?(path) ? YAML.safe_load_file(path, permitted_classes: [], aliases: false) || {} : {}
       validate_configuration!(configured)
-      { "manager" => "docker_compose", "compose_file" => "compose.yaml", "preferred_port" => 3000 }.merge(configured)
+      { "manager" => "docker_compose", "compose_file" => "compose.yaml", "preferred_port" => 3000,
+        "ports" => "manual" }.merge(configured)
     rescue Psych::Exception => e
       raise ConfigurationError, "Invalid brunch.yml: #{e.message}"
     end
@@ -101,7 +102,8 @@ module Brunch
       unknown = configured.keys - CONFIGURATION_KEYS
       raise ConfigurationError, "Unknown brunch.yml key(s): #{unknown.join(', ')}." unless unknown.empty?
 
-      value = { "manager" => "docker_compose", "compose_file" => "compose.yaml", "preferred_port" => 3000 }.merge(configured)
+      value = { "manager" => "docker_compose", "compose_file" => "compose.yaml", "preferred_port" => 3000,
+                "ports" => "manual" }.merge(configured)
       unless %w[docker_compose podman_compose local_process command].include?(value["manager"])
         raise ConfigurationError, "Unknown Brunch manager: #{value['manager']}."
       end
@@ -111,6 +113,10 @@ module Brunch
       if %w[docker_compose podman_compose].include?(value["manager"]) && (!value["compose_file"].is_a?(String) || value["compose_file"].empty?)
         raise ConfigurationError, "compose_file must be a non-empty string."
       end
+      raise ConfigurationError, "ports must be manual or auto." unless %w[manual auto].include?(value["ports"])
+      if value["ports"] == "auto" && !%w[docker_compose podman_compose].include?(value["manager"])
+        raise ConfigurationError, "ports: auto requires a Docker Compose or Podman Compose manager."
+      end
       if value["manager"] == "local_process" && (!value["command"].is_a?(String) || value["command"].empty?)
         raise ConfigurationError, "local_process manager requires a non-empty command."
       end

data/lib/brunch/compose_ports.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Brunch
+  # Reads the resolved Compose model produced by `compose config` and changes
+  # only published host ports. Keeping this separate from the source YAML lets
+  # Brunch use existing Compose projects without asking them to add variables.
+  module ComposePorts
+    module_function
+
+    def extract(document)
+      services = document.fetch("services", {})
+      raise CLI::ConfigurationError, "Compose config must contain a services mapping." unless services.is_a?(Hash)
+
+      services.flat_map do |service, definition|
+        next [] unless definition.is_a?(Hash)
+
+        Array(definition["ports"]).filter_map do |port|
+          published_mapping(service, port)
+        end
+      end
+    end
+
+    def rewrite(document, assignments)
+      indexed = assignments.to_h { |assignment| [key(assignment), assignment.fetch("host")] }
+      document.fetch("services", {}).each do |service, definition|
+        next unless definition.is_a?(Hash)
+
+        definition["ports"] = Array(definition["ports"]).map do |port|
+          mapping = published_mapping(service, port)
+          next port unless mapping
+
+          port.merge("published" => indexed.fetch(key(mapping)))
+        end
+      end
+      document
+    end
+
+    def key(mapping)
+      [mapping.fetch("service"), mapping.fetch("target"), mapping.fetch("protocol"), mapping.fetch("host_ip")]
+    end
+
+    def published_mapping(service, port)
+      raise CLI::ConfigurationError, "Unsupported Compose port for #{service}; use Compose long syntax with ports: auto." unless port.is_a?(Hash)
+      return unless port.key?("published") && !port["published"].to_s.empty?
+
+      published = integer(port["published"], "published host port for #{service}")
+      target = integer(port["target"], "container port for #{service}")
+      protocol = port.fetch("protocol", "tcp")
+      raise CLI::ConfigurationError, "Unsupported protocol #{protocol.inspect} for #{service}." unless %w[tcp udp].include?(protocol)
+
+      { "service" => service.to_s, "target" => target, "protocol" => protocol,
+        "host_ip" => port.fetch("host_ip", "").to_s, "published" => published }
+    end
+    private_class_method :published_mapping
+
+    def integer(value, description)
+      Integer(value).tap do |port|
+        raise CLI::ConfigurationError, "Invalid #{description}: #{value.inspect}." unless CLI::PORT_RANGE.cover?(port)
+      end
+    rescue ArgumentError, TypeError
+      raise CLI::ConfigurationError, "Invalid #{description}: #{value.inspect}."
+    end
+    private_class_method :integer
+  end
+end

data/lib/brunch/managers.rb

@@ -98,6 +98,13 @@ module Brunch
         compose(entry, "logs", *arguments)
       end
 
+      def render_compose(entry)
+        output, error, status = Open3.capture3(environment(entry), *source_compose_command(entry, "config"), **compose_options(entry))
+        return [output, nil] if status.success?
+
+        [nil, error]
+      end
+
       def port_available?(port)
         ports, = Open3.capture2(*ports_command)
         return false if ports.match?(/:#{port}->/)
@@ -125,11 +132,19 @@ module Brunch
 
       def compose_command(entry, *arguments)
         directory = compose_directory(entry)
-        compose_file = File.join(directory, entry.fetch("compose_file"))
+        compose_file = entry.fetch("rendered_compose", File.join(directory, entry.fetch("compose_file")))
         ["docker", "compose", "--project-name", entry.fetch("project"), "--project-directory", directory, "--file",
          compose_file, *arguments]
       end
 
+      def source_compose_command(entry, *arguments)
+        directory = entry.fetch("snapshot")
+        ["docker", "compose", "--project-name", entry.fetch("project"), "--project-directory", directory, "--file",
+         File.join(directory, entry.fetch("compose_file")), *arguments]
+      end
+
+      def compose_options(_entry) = {}
+
       def compose_directory(entry)
         source = entry.fetch("snapshot")
         File.file?(File.join(source, entry.fetch("compose_file"))) ? source : entry.fetch("control", source)
@@ -138,7 +153,7 @@ module Brunch
       def ports_command = ["docker", "ps", "--format", "{{.Ports}}"]
 
       def compose(entry, *arguments)
-        system(environment(entry), *compose_command(entry, *arguments))
+        system(environment(entry), *compose_command(entry, *arguments), **compose_options(entry))
       end
     end
 
@@ -159,14 +174,21 @@ module Brunch
 
       def compose_command(entry, *arguments)
         directory = compose_directory(entry)
-        compose_file = File.join(directory, entry.fetch("compose_file"))
+        compose_file = entry.fetch("rendered_compose", File.join(directory, entry.fetch("compose_file")))
         ["podman", "compose", "-p", entry.fetch("project"), "-f", compose_file, *arguments]
       end
 
+      def source_compose_command(entry, *arguments)
+        directory = entry.fetch("snapshot")
+        ["podman", "compose", "-p", entry.fetch("project"), "-f", File.join(directory, entry.fetch("compose_file")), *arguments]
+      end
+
+      def compose_options(entry) = { chdir: entry.fetch("snapshot") }
+
       def ports_command = ["podman", "ps", "--format", "{{.Ports}}"]
 
       def compose(entry, *arguments)
-        system(environment(entry), *compose_command(entry, *arguments), chdir: compose_directory(entry))
+        system(environment(entry), *compose_command(entry, *arguments), **compose_options(entry))
       end
     end
 

data/lib/brunch/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Brunch
-  VERSION = "0.9.2"
+  VERSION = "1.1.0"
 end

data/lib/brunch/worktree_mode.rb

@@ -24,14 +24,16 @@ module Brunch
       in ["branch-settled", ref, token] then settle_deleted_branch(ref, token)
       in ["cleanup"] | ["register", _] then worktree_cleanup
       in ["status"] then worktree_status
-      in ["list"] then worktree_ports
+      in ["list"] | ["ports"] then worktree_ports
       in ["watch"] then worktree_watch
       in ["port"] then worktree_port
+      in ["port", service, target] then worktree_port(service, target)
       in ["logs", *arguments] then worktree_logs(arguments)
       in ["run", "--", *command] if !command.empty? then worktree_run(command)
       in ["doctor"] then worktree_doctor
       else
-        warn "Usage: brunch {activate|start <current-ref>|stop|restart|status|list|watch|port|logs [args]|run -- <cmd>|doctor|cleanup}"
+        warn "Usage: brunch {activate|start <current-ref>|stop|restart|status|list|ports|watch|" \
+             "port [service container-port]|logs [args]|run -- <cmd>|doctor|cleanup}"
         return 64
       end
       0
@@ -87,12 +89,72 @@ module Brunch
     end
 
     def worktree_port_for(id, data, manager, base: preferred_port)
-      reserved = data.fetch("worktrees", {}).values.map { |record| record["port"] }
+      reserved = reserved_ports(data)
       (base..CLI::PORT_RANGE.end).chain(CLI::PORT_RANGE.begin...base).find do |port|
         !reserved.include?(port) && manager.port_available?(port)
       end || abort("No free port for worktree #{id}.")
     end
 
+    def reserved_ports(data)
+      assigned_ports(data).uniq
+    end
+
+    def assigned_ports(data)
+      data.fetch("worktrees", {}).values.flat_map do |record|
+        [record["port"], *Array(record["ports"]).map { |mapping| mapping["host"] }]
+      end.compact
+    end
+
+    def auto_ports?(config) = config.fetch("ports") == "auto"
+
+    def reserve_compose_ports(id, data, manager, mappings)
+      record = data.fetch("worktrees").fetch(id)
+      known = Array(record["ports"])
+      all_reserved = reserved_ports(data)
+      assignments = mappings.map do |mapping|
+        existing = known.find { |candidate| ComposePorts.key(candidate) == ComposePorts.key(mapping) }
+        next existing if existing
+
+        preferred = mapping.fetch("published")
+        host = if known.empty? && record["port"] == preferred
+                 preferred
+               elsif !all_reserved.include?(preferred) && manager.port_available?(preferred)
+                 preferred
+               else
+                 worktree_port_for(id, data, manager, base: preferred)
+               end
+        assignment = mapping.merge("host" => host)
+        known << assignment
+        all_reserved << host
+        assignment
+      end
+      record["ports"] = known
+      record["port"] = assignments.first.fetch("host") unless assignments.empty?
+      assignments
+    end
+
+    def render_compose_ports(path, entry, manager)
+      rendered, error = manager.render_compose(entry)
+      abort "Could not render #{entry.fetch('compose_file')}: #{error.strip}" unless rendered
+
+      document = YAML.safe_load(rendered, permitted_classes: [], aliases: false)
+      mappings = ComposePorts.extract(document)
+      assignments = nil
+      with_state_lock do |data|
+        assignments = reserve_compose_ports(worktree_identity(path), data, manager, mappings)
+      end
+      ComposePorts.rewrite(document, assignments)
+      target = File.join(entry.fetch("control"), "brunch-compose.yaml")
+      FileUtils.mkdir_p(File.dirname(target))
+      File.write(target, YAML.dump(document))
+      entry["ports"] = assignments
+      entry["port"] = assignments.first.fetch("host") unless assignments.empty?
+      entry["rendered_compose"] = target
+      entry
+    rescue Psych::Exception => e
+      raise CLI::ConfigurationError, "Could not parse rendered Compose configuration: #{e.message}"
+    end
+
     def worktree_activate(path, force: false)
       path = File.realpath(path)
       id = worktree_identity(path)
@@ -130,16 +192,16 @@ module Brunch
         end
         if existing && !force && existing["snapshot"] == path && existing["status"] != "starting"
           with_state_lock { |data| data.fetch("worktrees").fetch(id)["current"] = ref }
-          unless worktree_manager(existing).resume(existing)
-            abort "Could not resume environment for #{path}; the container may have exited. Check brunch logs. " \
-                  "If dependencies changed, rebuild with brunch restart (this replaces the container)."
+          if worktree_manager(existing).resume(existing)
+            with_state_lock do |data|
+              data.fetch("worktrees").fetch(id).fetch("environments").fetch(ref)["status"] = "running"
+            end
+            puts "Resumed #{ref} in #{path} at http://127.0.0.1:#{existing.fetch('port')}"
+            return
           end
 
-          with_state_lock do |data|
-            data.fetch("worktrees").fetch(id).fetch("environments").fetch(ref)["status"] = "running"
-          end
-          puts "Resumed #{ref} in #{path} at http://127.0.0.1:#{existing.fetch('port')}"
-          return
+          warn "Could not resume #{ref}; recreating its environment."
+          force = true
         end
         abort "Could not reset environment for #{path}." if existing && !worktree_manager(existing).reset(existing)
 
@@ -150,13 +212,16 @@ module Brunch
         if %w[docker_compose podman_compose].include?(config.fetch("manager"))
           source_file = File.join(path, compose_file)
           abort "Missing #{compose_file} in #{path}." unless File.file?(source_file)
-          destination = File.join(control, compose_file)
-          FileUtils.mkdir_p(File.dirname(destination))
-          FileUtils.cp(source_file, destination)
+          unless auto_ports?(config)
+            destination = File.join(control, compose_file)
+            FileUtils.mkdir_p(File.dirname(destination))
+            FileUtils.cp(source_file, destination)
+          end
         end
         entry = { "source_type" => "worktree", "snapshot" => path, "control" => control,
                   "ref" => ref, "head" => head, "port" => port, "project" => project,
                   "compose_file" => compose_file, "configuration" => config, "status" => "starting" }
+        entry = render_compose_ports(path, entry, manager) if auto_ports?(config)
         with_state_lock do |data|
           record = data.fetch("worktrees").fetch(id)
           record.fetch("environments")[ref] = entry
@@ -167,7 +232,7 @@ module Brunch
         with_state_lock do |data|
           data.fetch("worktrees").fetch(id).fetch("environments")[ref] = entry.merge("status" => "running")
         end
-        puts "Started #{ref} in #{path} at http://127.0.0.1:#{port}"
+        puts "Started #{ref} in #{path} at http://127.0.0.1:#{entry.fetch('port')}"
       end
     end
 
@@ -331,7 +396,7 @@ module Brunch
         renamed = renamed_branch(ref, nil, refs)
         next if renamed == :unknown
 
-        renamed ? rename_branch_environments(ref, renamed) : remove_branch_environments(ref)
+        renamed ? rename_branch_environments(ref, renamed, replace_existing: true) : remove_branch_environments(ref)
       end
     end
 
@@ -405,7 +470,8 @@ module Brunch
       record, current = current_worktree_entry(data)
       return puts "No Brunch environment in this worktree." unless current
 
-      puts "#{current.fetch('ref')} (#{record.fetch('path')}): #{worktree_manager(current).status(current)}, http://127.0.0.1:#{record.fetch('port')}"
+      puts "#{current.fetch('ref')} (#{record.fetch('path')}): #{worktree_manager(current).status(current)}, http://127.0.0.1:#{current.fetch('port')}"
+      print_port_mappings(current)
     end
 
     def worktree_ports
@@ -422,11 +488,11 @@ module Brunch
           prefix = index == branches.length - 1 ? "  └─" : "  ├─"
           running = ref == record["current"] && entry["status"] == "running"
           unless running
-            puts color("#{prefix} ○ #{ref}  #{entry.fetch('port')}", 90)
+            puts color("#{prefix} ○ #{ref}  #{port_label(entry)}", 90)
             next
           end
 
-          puts "#{prefix} #{color("● #{ref}", 32)}  #{entry.fetch('port')}"
+          puts "#{prefix} #{color("● #{ref}", 32)}  #{port_label(entry)}"
         end
       end
     end
@@ -445,11 +511,31 @@ module Brunch
       puts "\nStopped watching."
     end
 
-    def worktree_port
-      record, = current_worktree_entry(state)
-      raise CLI::OperationError, "No Brunch environment in this worktree." unless record
+    def worktree_port(service = nil, target = nil)
+      _record, entry = current_worktree_entry(state)
+      raise CLI::OperationError, "No Brunch environment in this worktree." unless entry
+
+      return puts entry.fetch("port") unless service
+
+      mapping = Array(entry["ports"]).find do |candidate|
+        candidate["service"] == service && candidate["target"].to_s == target
+      end
+      raise CLI::OperationError, "No published port for #{service}:#{target}." unless mapping
 
-      puts record.fetch("port")
+      puts mapping.fetch("host")
+    end
+
+    def port_label(entry)
+      mappings = Array(entry["ports"])
+      return entry.fetch("port").to_s if mappings.empty?
+
+      mappings.map { |mapping| "#{mapping.fetch('service')}:#{mapping.fetch('target')}/#{mapping.fetch('protocol')}→#{mapping.fetch('host')}" }.join(", ")
+    end
+
+    def print_port_mappings(entry)
+      Array(entry["ports"]).each do |mapping|
+        puts "  #{mapping.fetch('service')}:#{mapping.fetch('target')}/#{mapping.fetch('protocol')} → 127.0.0.1:#{mapping.fetch('host')}"
+      end
     end
 
     def worktree_logs(arguments)
@@ -469,7 +555,7 @@ module Brunch
 
     def worktree_doctor
       data = state
-      ports = data.fetch("worktrees", {}).values.map { |record| record["port"] }
+      ports = assigned_ports(data)
       paths = worktree_paths
       hooks_dir = git_output("rev-parse", "--git-path", "hooks")
       checks = {

data/lib/brunch.rb

@@ -2,6 +2,7 @@
 
 require_relative "brunch/version"
 require_relative "brunch/managers"
+require_relative "brunch/compose_ports"
 require_relative "brunch/branch_settlement"
 require_relative "brunch/worktree_mode"
 require_relative "brunch/cli"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brunch
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 1.1.0
 platform: ruby
 authors:
 - Maciej Ciemborowicz
@@ -94,6 +94,7 @@ files:
 - lib/brunch.rb
 - lib/brunch/branch_settlement.rb
 - lib/brunch/cli.rb
+- lib/brunch/compose_ports.rb
 - lib/brunch/hooks.rb
 - lib/brunch/managers.rb
 - lib/brunch/version.rb