brunch 0.0.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 0446f4c84c8e70a7178c9de33468d90d7747c12b
-  data.tar.gz: 4f08030c58640bbbeea3a2078083bca77744461e
+SHA256:
+  metadata.gz: f77dd24e00604eea2485dff005164094eb6f6e8633d81e96616df5bf25420ef2
+  data.tar.gz: 578505da516fbd81dfdd6c54e397ac0d4861e25e7af5b482a6e4f8fcf2aa4043
 SHA512:
-  metadata.gz: 0dc5753a95e229da0bf221648a291b8c745194e4798674fa3ab377f8cce5d7969843780791db8dd12d0767b4f6001ed5ac0f3a58c6b9c12abdeb7e9ea5217ff2
-  data.tar.gz: 2e2a24eb7ce8c920cef40c55bc744c0399c81653872eca813aa25aa395a6ca86ef42abf0f022123a7bd9e4a876a6528409121ff39954ebe742af04210d185202
+  metadata.gz: c80c84a7078a91a71c69517d68d9b5093d13c6e97b8662e5ec98aecf2b2d2b07daaa49713da6046c51ca16c41c63cc58b50c2e6c286f1c5ede0ed0c3f2ce5ab2
+  data.tar.gz: 759c3e32ad7957cdec4b3babe27ad211262ce4f177b0ce6a2f4a0f9d3db26ed81ed332c930e2690e7cc3f9195f7528a5fa80b5ddf8cd4aa7063c32f9e0c18648

data/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+## Unreleased
+
+## 0.8.0 - 2026-09-29
+
+- Use one worktree-based lifecycle for both branch switches and parallel
+  worktrees. Branches within a worktree reuse its port; separate worktrees
+  receive distinct host ports.
+- Run applications from the live worktree and replace mode-specific port
+  settings with an optional `preferred_port`.
+- Document installation and everyday use, and add a compact illustration to
+  the README.
+- Make CI lint only project files, install the `ghe` alias, and initialize the
+  test repository on `main`.
+- Detect running Podman Compose containers by their project label.
+
+## 0.7.1 - 2026-09-29
+
+- Use a compatible Podman Compose provider and CLI arguments in integration
+  tests and at runtime.
+
+## 0.7.0 - 2026-09-29
+
+- Add parallel worktree mode with per-worktree ports, live source directories,
+  isolated projects and volumes, and branch-specific environments.
+- Handle git-hooks-ext worktree create, remove, move, prune, and repair events;
+  reconcile plain Git worktree operations during cleanup.
+- Preserve control files for teardown after a worktree disappears, and use
+  short repository locks plus per-worktree lifecycle locks.
+
+## 0.6.0 - 2026-09-29
+
+- Add shared and unique port modes; shared port `3000` is now the default.
+
+## 0.5.0 - 2026-09-28
+
+- Add `ports` and script-friendly `port` commands.
+
+## 0.4.1 - 2026-09-28
+
+- Strengthen `doctor` hook and port validation.
+
+## 0.4.0 - 2026-09-28
+
+- Add `doctor`, `exec`, and argument forwarding for `logs`.
+- Serialize commands with a repository-local lock, save state atomically, and
+  recover interrupted environment setup on the next activation.
+- Add conditional Docker Compose and Podman Compose integration tests to CI.
+
+## 0.3.0 - 2026-09-28
+
+- Add a native `local_process` manager for `bin/dev`-style commands, with PID
+  tracking, process-group shutdown, and snapshot-local logs.
+
+## 0.2.0 - 2026-09-28
+
+- Add pluggable environment managers. Docker Compose remains the default and a
+  command-based manager supports other project-specific runtimes.
+- Add an optional `create` lifecycle command for provisioning custom-manager
+  environments before they start.
+- Add the Podman Compose manager, configurable `switch_only` and `active_only`
+  lifecycle modes, and `status`, `stop`, `restart`, and `logs` commands.
+- Validate `brunch.yml` and expose manager status and health checks.
+
+## 0.1.0 - 2026-09-28
+
+- Initial public release.
+- Isolated Docker Compose environments activated by Git branch checkout.
+- `git-hooks-ext` integration and stale-environment cleanup.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maciej Ciemborowicz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,243 @@
+# Brunch
+
+![Brunch — container per branch and worktree](brunch.webp)
+
+Brunch runs isolated development environments for Git worktrees. The main
+checkout is a worktree too: switching branches there reuses its port, while
+additional worktrees run in parallel on different host ports. Docker Compose
+is the default manager; Podman
+Compose, local processes, and project commands are also supported.
+
+Each branch environment has a distinct Compose project name, network, and
+named volumes. The active environment runs from its live worktree directory,
+including uncommitted changes when the manager rebuilds or reloads the app.
+
+## Requirements
+
+- Ruby 3.1 or newer
+- Git 2.28 or newer
+- A supported environment manager: Docker Compose, Podman Compose, or project commands
+- [`git-hooks-ext`](https://github.com/ciembor/git-hooks-ext)
+
+## Installation
+
+Install [`git-hooks-ext`](https://github.com/ciembor/git-hooks-ext) so that
+`ghe` is on your `PATH`, then install Brunch:
+
+```sh
+gem install brunch
+```
+
+Run `brunch install` inside each Git repository you want Brunch to manage.
+It installs the `git-hooks-ext` bridge and project-local hooks, and refuses
+to replace an existing hook owned by another tool.
+
+## Project configuration
+
+Add `brunch.yml` to the project root. Docker Compose is the default, so the
+following remains sufficient for Compose projects:
+
+```yaml
+compose_file: compose.yaml
+```
+
+The referenced Compose file belongs to the application. Brunch does not impose
+a database or service stack: applications may define PostgreSQL, MySQL, Redis,
+Sidekiq, Elasticsearch, or any other services they need.
+Unknown `brunch.yml` fields are errors, so configuration typos are not ignored.
+
+Expose the application port with `BRUNCH_PORT`:
+
+```yaml
+services:
+  web:
+    ports:
+      - "127.0.0.1:${BRUNCH_PORT}:3000"
+```
+
+The first activated worktree prefers `127.0.0.1:3000`. Every worktree keeps
+its assigned host port while its branches take turns using it. Other worktrees
+receive a different free port; running containers can never bind the same host
+address and port. To prefer another starting port, set `preferred_port: 4000`.
+Brunch persists assignments privately in `.git/brunch/state.json`.
+
+## Using Brunch
+
+First, commit `brunch.yml` and your Compose file (or the configuration for
+another manager). The repository needs at least one commit before Brunch can
+start an environment. Install the hooks once per repository, then activate
+the checked-out branch:
+
+```sh
+brunch install
+brunch doctor
+brunch activate
+brunch status
+brunch port
+```
+
+Open `http://127.0.0.1:3000` if port 3000 is free, or use the port printed by
+`brunch activate` / `brunch port`. Brunch starts the application in the
+background. With Compose, the app must listen on the container port mapped in
+`compose.yaml`.
+
+### Branches in one checkout
+
+Once the hooks are installed, ordinary Git branch switches stop the old
+environment and start the new one automatically:
+
+```sh
+git switch -c feature/login
+brunch status
+git switch main
+```
+
+Both branches use this checkout's assigned host port. With Compose, they keep
+separate projects and volumes. To start the checked-out branch manually (for
+example, after `brunch stop`), run `brunch activate`. Run `brunch restart` to
+rebuild it after changing files that are copied into the image.
+
+### Parallel worktrees
+
+There is no mode switch. Commit the same `brunch.yml` in your repository, then
+create additional worktrees. Run `brunch install` again after upgrading Brunch
+to install its worktree hooks.
+
+```sh
+ghe worktree add -b feature-a ../feature-a
+ghe worktree add -b feature-b ../feature-b
+cd ../feature-a
+brunch port        # port for this worktree
+brunch ports       # ports for all worktrees
+```
+
+Each worktree runs independently on a different host port, so `feature-a` and
+`feature-b` can be used at the same time. Run `brunch status` or `brunch port`
+inside each worktree to find its address. Switching branches inside one
+worktree does not stop the others.
+
+`ghe worktree add`, `move`, and `remove` emit lifecycle events. Git's
+`post-checkout` hook handles branch changes inside any worktree, including the
+main checkout. If you use plain `git worktree add`, run `brunch activate` in the
+new worktree; after a plain move or removal, run `brunch cleanup` from a
+remaining worktree.
+
+The source directory is never deleted by Brunch. It keeps a separate control
+copy under `.git/brunch/controls` so it can shut down Compose or run a custom
+`remove` command after a worktree has been removed. Switching branches within
+one worktree keeps the old branch's environment stopped, with its own named
+volumes. Removing the worktree removes all of its Brunch environments. The
+`local_process` manager also writes its log to the control directory, keeping
+the worktree clean. Custom `remove` commands that depend on project files must
+be committed, because the control copy is based on the worktree's last commit.
+
+Docker builds read uncommitted files from the live worktree. To see edits in
+an already running container without rebuilding, configure a source bind
+mount or another reload mechanism in the project's Compose file.
+`brunch restart` rebuilds the current environment.
+
+Before upgrading from an older branch-only configuration, stop its running
+environment and clean up its legacy state. Brunch refuses to reinterpret an
+old non-empty branch state as worktree state, preventing orphaned containers.
+
+### Custom manager commands
+
+Use the `command` manager when the project is started by another tool. Brunch
+runs commands from the live worktree with these variables: `BRUNCH_REF`,
+`BRUNCH_PORT`, `BRUNCH_PROJECT`, and `BRUNCH_SNAPSHOT`. The last variable points
+to the live worktree for compatibility with manager adapters.
+
+```yaml
+manager: command
+commands:
+  create: bin/environment create
+  start: bin/environment start
+  stop: bin/environment stop
+  remove: bin/environment remove
+```
+
+`create` provisions manager-owned resources; it is optional for the `command`
+manager. `start` must return after
+it has launched the environment (for example, by delegating to a daemon or
+supervisor). `stop` is used when switching branches; `remove` is used when
+a worktree is deleted and should remove any manager-owned persistent
+resources. This makes the adapter suitable for Podman, Kubernetes wrappers,
+Foreman/Overmind wrappers, or a project-specific script.
+
+Optional `status`, `health`, and `logs` commands power the corresponding Brunch
+commands. A successful `health` command reports a healthy environment.
+
+### Podman Compose
+
+Podman Compose uses the same Compose file contract as Docker Compose:
+
+```yaml
+manager: podman_compose
+compose_file: compose.yaml
+```
+
+### Local process
+
+Use `local_process` for a development command such as `bin/dev`.
+Brunch starts it in a dedicated process group, records its PID, stops that
+group on a branch switch, and saves its output under `.git/brunch/controls`.
+
+```yaml
+manager: local_process
+command: bin/dev
+```
+
+## Lifecycle
+
+- A branch checkout stops the previous environment in that worktree, then
+  creates and starts the new one on the same port.
+- Each worktree keeps its own current environment and port. Other worktrees
+  continue running during branch switches.
+- Checking out a remote branch into a new local tracking branch works through
+  the same `post-checkout` hook.
+- `brunch cleanup` removes environments belonging to deleted worktrees.
+
+Git 2.39 cannot reliably report a normal `git branch -d` operation to a hook.
+Stopped branch environments remain until their worktree is removed.
+
+## Operations
+
+```sh
+brunch status    # current worktree environment, manager status and port
+brunch ports     # worktree-to-port list; current worktree is marked in green
+brunch port      # only the current worktree's port, suitable for scripts
+brunch stop      # stop the active environment without deleting it
+brunch restart   # recreate and start the active environment
+brunch logs      # show the last 100 logs (or run commands.logs)
+brunch logs --follow
+brunch run -- bin/rails console  # runs on the host in the live worktree, not in a container
+brunch doctor    # verify Git, installed hooks, configuration, manager and ports
+brunch cleanup   # delete environments for removed worktrees
+```
+
+Brunch coordinates commands with locks under `.git/brunch`, writes `state.json`
+atomically, and retries interrupted environment setup on the next activation.
+
+## Development
+
+```sh
+bundle install
+bin/install-pre-commit
+bundle exec rake quality
+gem build brunch.gemspec
+```
+
+Container E2E tests use real temporary Git repositories, Compose containers,
+and HTTP requests. Run them with Docker or Podman:
+
+```sh
+BRUNCH_INTEGRATION_MANAGER=docker_compose bundle exec rake test
+BRUNCH_INTEGRATION_MANAGER=podman_compose bundle exec rake test
+```
+
+CI runs both managers on pushes and pull requests. Without the environment
+variable, container tests are skipped by the local quality check.
+
+The pre-commit hook runs RuboCop with automatic corrections, Reek, and the full
+test suite. SimpleCov requires 100% line and branch coverage of `lib/**/*.rb`. When
+RuboCop changes a file, review and stage the correction before committing.

data/exe/brunch

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/brunch"
+
+exit Brunch::CLI.start(ARGV)

data/lib/brunch/cli.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "open3"
+require "yaml"
+
+module Brunch
+  class CLI
+    include WorktreeMode
+
+    PORT_RANGE = (1024..49_151)
+    CONFIGURATION_KEYS = %w[manager compose_file command commands preferred_port].freeze
+    COMMAND_KEYS = %w[create start stop remove status health logs].freeze
+
+    class ConfigurationError < StandardError; end
+    class OperationError < StandardError; end
+
+    def self.start(arguments) = new.start(arguments)
+
+    def start(arguments)
+      Dir.chdir(repo_root) unless Dir.pwd == repo_root
+      case arguments
+      in ["install"] then Hooks.install
+      in ["version"] | ["--version"] | ["-v"] then puts Brunch::VERSION
+      else return worktree_command(arguments)
+      end
+      0
+    rescue ConfigurationError => e
+      warn e.message
+      64
+    rescue OperationError => e
+      warn e.message
+      1
+    end
+
+    private
+
+    def git_output(*arguments)
+      output, status = Open3.capture2("git", *arguments)
+      abort "Git command failed: git #{arguments.join(' ')}" unless status.success?
+
+      output.strip
+    end
+
+    def repo_root
+      @repo_root ||= git_output("rev-parse", "--show-toplevel")
+    end
+
+    def state_root
+      common_dir = git_output("rev-parse", "--git-common-dir")
+      @state_root ||= File.join(File.expand_path(common_dir, repo_root), "brunch")
+    end
+
+    def state_path = File.join(state_root, "state.json")
+
+    def state
+      return { "worktrees" => {} } unless File.file?(state_path)
+
+      data = JSON.parse(File.read(state_path))
+      raise ConfigurationError, "Invalid Brunch state: expected a JSON object." unless data.is_a?(Hash)
+      if data.fetch("environments", {}).any? || data.key?("active_ref")
+        raise ConfigurationError, "Legacy branch state found in .git/brunch/state.json; stop old environments before upgrading."
+      end
+
+      data
+    rescue JSON::ParserError => e
+      raise ConfigurationError, "Invalid Brunch state: #{e.message}"
+    end
+
+    def save_state(value)
+      FileUtils.mkdir_p(state_root)
+      temporary_path = "#{state_path}.#{Process.pid}.tmp"
+      File.open(temporary_path, "w", 0o600) do |file|
+        file.write(JSON.pretty_generate(value))
+        file.flush
+        file.fsync
+      end
+      File.rename(temporary_path, state_path)
+    ensure
+      FileUtils.rm_f(temporary_path) if temporary_path
+    end
+
+    def configuration(root: repo_root)
+      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)
+    rescue Psych::Exception => e
+      raise ConfigurationError, "Invalid brunch.yml: #{e.message}"
+    end
+
+    def validate_configuration!(configured)
+      raise ConfigurationError, "brunch.yml must contain a mapping." unless configured.is_a?(Hash)
+
+      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)
+      unless %w[docker_compose podman_compose local_process command].include?(value["manager"])
+        raise ConfigurationError, "Unknown Brunch manager: #{value['manager']}."
+      end
+      unless value["preferred_port"].is_a?(Integer) && PORT_RANGE.cover?(value["preferred_port"])
+        raise ConfigurationError, "preferred_port must be a number from #{PORT_RANGE.begin} to #{PORT_RANGE.end}."
+      end
+      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
+      if value["manager"] == "local_process" && (!value["command"].is_a?(String) || value["command"].empty?)
+        raise ConfigurationError, "local_process manager requires a non-empty command."
+      end
+      return unless value["manager"] == "command"
+
+      commands = value["commands"]
+      raise ConfigurationError, "command manager requires a commands mapping." unless commands.is_a?(Hash)
+
+      unknown = commands.keys - COMMAND_KEYS
+      raise ConfigurationError, "Unknown commands key(s): #{unknown.join(', ')}." unless unknown.empty?
+
+      %w[start stop remove].each do |action|
+        raise ConfigurationError, "command manager requires commands.#{action}." unless commands[action].is_a?(String) && !commands[action].empty?
+      end
+      %w[create status health logs].each do |action|
+        raise ConfigurationError, "commands.#{action} must be a string." if commands.key?(action) && !commands[action].is_a?(String)
+      end
+    end
+
+    def preferred_port = configuration.fetch("preferred_port")
+
+    def archive_ref(ref, destination)
+      FileUtils.rm_rf(destination)
+      FileUtils.mkdir_p(destination)
+      environment = { "LC_ALL" => "C", "LANG" => "C" }
+      statuses = Open3.pipeline([environment, "git", "archive", "--format=tar", ref],
+                                [environment, "tar", "-x", "-C", destination])
+      abort "Could not create a control copy for #{ref}." unless statuses.all?(&:success?)
+    end
+
+    def color(text, code)
+      return text unless $stdout.tty?
+
+      "\e[#{code}m#{text}\e[0m"
+    end
+  end
+end

data/lib/brunch/hooks.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+
+module Brunch
+  module Hooks
+    EVENTS = %w[branch-created remote-branch-created remote-branch-updated post-checkout worktree-created
+                worktree-removed worktree-moved worktree-pruned worktree-repaired].freeze
+
+    module_function
+
+    def install
+      abort "git-hooks-ext must be installed before running this command." unless system("ghe", "--version",
+                                                                                         out: File::NULL, err: File::NULL)
+      abort "Could not install the git-hooks-ext bridge." unless system("ghe", "install")
+
+      hooks_dir = git_output("rev-parse", "--git-path", "hooks")
+      EVENTS.each { |event| install_hook(File.join(hooks_dir, event), event) }
+      puts "Brunch hooks are installed."
+    end
+
+    def dispatch(event, arguments)
+      case event
+      when "post-checkout"
+        CLI.start(["activate"]) if arguments.fetch(2, "0") == "1"
+      when "branch-created", "remote-branch-created", "remote-branch-updated"
+        CLI.start(["register", arguments.fetch(0)])
+      when "worktree-created", "worktree-removed", "worktree-moved", "worktree-pruned", "worktree-repaired"
+        CLI.start(["worktree-event", event, *arguments])
+      else
+        abort "Unknown hook event: #{event}"
+      end
+    end
+
+    def git_output(*arguments)
+      output, status = Open3.capture2("git", *arguments)
+      abort "Git command failed: git #{arguments.join(' ')}" unless status.success?
+
+      output.strip
+    end
+    private_class_method :git_output
+
+    def install_hook(path, event)
+      contents = hook_contents(event)
+      abort "Refusing to replace existing hook: #{path}" if File.exist?(path) && File.read(path) != contents && !brunch_hook?(path)
+
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, contents)
+      FileUtils.chmod(0o755, path)
+    end
+    private_class_method :install_hook
+
+    def brunch_hook?(path)
+      contents = File.read(path)
+      contents.include?("require \"brunch\"") && contents.include?("Brunch::Hooks.dispatch")
+    end
+    private_class_method :brunch_hook?
+
+    def hook_contents(event)
+      library_path = File.expand_path("../brunch.rb", __dir__)
+      <<~RUBY
+        #!#{Gem.ruby}
+        # frozen_string_literal: true
+
+        repo_root = `git rev-parse --show-toplevel`.strip
+        gemfile = File.join(repo_root, "Gemfile")
+        bundled = false
+        if File.file?(gemfile) && File.read(gemfile).match?(/gem[[:space:]]+["']brunch["']/)
+          ENV["BUNDLE_GEMFILE"] = gemfile
+          begin
+            require "bundler/setup"
+            bundled = true
+          rescue LoadError, StandardError
+            ENV.delete("BUNDLE_GEMFILE")
+          end
+        end
+
+        if !bundled && File.file?(gemfile)
+          require #{library_path.inspect}
+        else
+          require "brunch"
+        end
+        Brunch::Hooks.dispatch(#{event.inspect}, ARGV)
+      RUBY
+    end
+    private_class_method :hook_contents
+  end
+end

data/lib/brunch/managers.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require "socket"
+
+module Brunch
+  module Managers
+    class Base
+      def initialize(configuration)
+        @configuration = configuration
+      end
+
+      def available? = true
+
+      def create(_entry) = true
+
+      def environment(entry)
+        {
+          "BRUNCH_REF" => entry.fetch("ref", ""),
+          "BRUNCH_PORT" => entry.fetch("port").to_s,
+          "BRUNCH_PROJECT" => entry.fetch("project"),
+          "BRUNCH_SNAPSHOT" => entry.fetch("snapshot")
+        }
+      end
+
+      def port_available?(port)
+        socket = TCPSocket.new("127.0.0.1", port)
+        socket.close
+        false
+      rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ENETUNREACH
+        true
+      end
+
+      def stop(_entry); end
+
+      def status(_entry) = "unknown"
+
+      def healthy?(_entry) = false
+
+      def logs(_entry, *_arguments)
+        warn "Logs are not supported by this manager."
+        false
+      end
+
+      def reset(entry)
+        stop(entry)
+        remove_managed_files(entry)
+      end
+
+      def remove(entry)
+        stop(entry)
+        remove_managed_files(entry)
+        true
+      end
+
+      def remove_managed_files(entry)
+        target = entry["source_type"] == "worktree" ? entry["control"] : entry.fetch("snapshot")
+        FileUtils.rm_rf(target) if target
+      end
+    end
+
+    class DockerCompose < Base
+      def available?
+        system("docker", "info", out: File::NULL, err: File::NULL)
+      end
+
+      def start(entry) = compose(entry, "up", "--detach", "--build", "--remove-orphans")
+
+      def status(entry)
+        return "unavailable" unless available?
+
+        healthy?(entry) ? "running" : "stopped"
+      end
+
+      def healthy?(entry)
+        return false unless available?
+
+        output, status = Open3.capture2(*compose_command(entry, "ps", "--status", "running", "--quiet"))
+        status.success? && !output.strip.empty?
+      end
+
+      def logs(entry, *arguments)
+        arguments = ["--tail", "100"] if arguments.empty?
+        compose(entry, "logs", *arguments)
+      end
+
+      def port_available?(port)
+        ports, = Open3.capture2(*ports_command)
+        return false if ports.match?(/:#{port}->/)
+
+        super
+      end
+
+      def stop(entry)
+        compose(entry, "stop") if available?
+      end
+
+      def reset(entry)
+        compose(entry, "down", "--remove-orphans") if available?
+        remove_managed_files(entry)
+      end
+
+      def remove(entry)
+        return false unless available? && compose(entry, "down", "--volumes", "--remove-orphans")
+
+        remove_managed_files(entry)
+        true
+      end
+
+      private
+
+      def compose_command(entry, *arguments)
+        directory = compose_directory(entry)
+        compose_file = File.join(directory, entry.fetch("compose_file"))
+        ["docker", "compose", "--project-name", entry.fetch("project"), "--project-directory", directory, "--file",
+         compose_file, *arguments]
+      end
+
+      def compose_directory(entry)
+        source = entry.fetch("snapshot")
+        File.file?(File.join(source, entry.fetch("compose_file"))) ? source : entry.fetch("control", source)
+      end
+
+      def ports_command = ["docker", "ps", "--format", "{{.Ports}}"]
+
+      def compose(entry, *arguments)
+        system(environment(entry), *compose_command(entry, *arguments))
+      end
+    end
+
+    class PodmanCompose < DockerCompose
+      def available?
+        system("podman", "info", out: File::NULL, err: File::NULL)
+      end
+
+      def healthy?(entry)
+        return false unless available?
+
+        output, status = Open3.capture2("podman", "ps", "--filter",
+                                        "label=com.docker.compose.project=#{entry.fetch('project')}", "--quiet")
+        status.success? && !output.strip.empty?
+      end
+
+      private
+
+      def compose_command(entry, *arguments)
+        directory = compose_directory(entry)
+        compose_file = File.join(directory, entry.fetch("compose_file"))
+        ["podman", "compose", "-p", entry.fetch("project"), "-f", compose_file, *arguments]
+      end
+
+      def ports_command = ["podman", "ps", "--format", "{{.Ports}}"]
+
+      def compose(entry, *arguments)
+        system(environment(entry), *compose_command(entry, *arguments), chdir: compose_directory(entry))
+      end
+    end
+
+    class LocalProcess < Base
+      def start(entry)
+        log_directory = entry["source_type"] == "worktree" ? entry.fetch("control") : entry.fetch("snapshot")
+        log_path = File.join(log_directory, ".brunch.log")
+        entry["pid"] =
+          Process.spawn(environment(entry), "sh", "-lc", @configuration.fetch("command"), chdir: entry.fetch("snapshot"),
+                                                                                          out: [log_path, "a"], err: [log_path, "a"], pgroup: true)
+        entry["log_path"] = log_path
+        Process.detach(entry.fetch("pid"))
+        true
+      end
+
+      def stop(entry)
+        pid = entry["pid"]
+        return true unless pid
+
+        Process.kill("TERM", -pid)
+        true
+      rescue Errno::ESRCH
+        true
+      end
+
+      def status(entry) = running?(entry) ? "running" : "stopped"
+      def healthy?(entry) = running?(entry)
+
+      def logs(entry, *arguments)
+        return super unless arguments.empty?
+
+        path = entry["log_path"]
+        return super unless path && File.file?(path)
+
+        puts File.readlines(path).last(100)
+        true
+      end
+
+      private
+
+      def running?(entry)
+        Process.kill(0, entry.fetch("pid"))
+        true
+      rescue Errno::ESRCH
+        false
+      end
+    end
+
+    # Runs project-provided commands, making Brunch compatible with tools such
+    # as Podman, Kubernetes wrappers, Foreman, or custom process supervisors.
+    class Command < Base
+      def create(entry) = run("create", entry, optional: true)
+      def start(entry) = run("start", entry)
+      def stop(entry) = run("stop", entry)
+
+      def remove(entry)
+        run("remove", entry) && super
+      end
+
+      def status(entry)
+        if command?("status")
+          run("status", entry) ? "running" : "stopped"
+        else
+          "unknown"
+        end
+      end
+
+      def healthy?(entry)
+        return false unless command?("health")
+
+        run("health", entry)
+      end
+
+      def logs(entry, *arguments)
+        return super unless command?("logs")
+
+        run("logs", entry, arguments: arguments)
+      end
+
+      private
+
+      def run(action, entry, optional: false, arguments: [])
+        command = @configuration.fetch("commands")[action]
+        return true if optional && !command
+
+        abort "Missing commands.#{action} for the command manager." unless command
+        directory = if File.directory?(entry.fetch("snapshot"))
+                      entry.fetch("snapshot")
+                    else
+                      entry.fetch("control",
+                                  entry.fetch("snapshot"))
+                    end
+        system(environment(entry), "sh", "-lc", command, "brunch", *arguments, chdir: directory)
+      end
+
+      def command?(action) = @configuration.fetch("commands").key?(action)
+    end
+
+    module_function
+
+    def build(configuration)
+      case configuration.fetch("manager")
+      when "docker_compose" then DockerCompose.new(configuration)
+      when "podman_compose" then PodmanCompose.new(configuration)
+      when "local_process" then LocalProcess.new(configuration)
+      when "command" then Command.new(configuration)
+      else abort "Unknown Brunch manager: #{configuration.fetch('manager')}."
+      end
+    end
+  end
+end

data/lib/brunch/version.rb

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

data/lib/brunch/worktree_mode.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Brunch
+  module WorktreeMode
+    def worktree_command(arguments)
+      case arguments
+      in ["worktree-event", "worktree-created", path, *_]
+        worktree_activate(path) if File.directory?(path)
+      in ["worktree-event", "worktree-removed" | "worktree-pruned", path, *_]
+        worktree_remove(path)
+      in ["worktree-event", "worktree-moved", old_path, new_path, *_]
+        worktree_move(old_path, new_path)
+      in ["worktree-event", "worktree-repaired", path, *_]
+        worktree_repair(path) if File.directory?(path)
+      in ["activate"] then worktree_activate(repo_root)
+      in ["restart"] then worktree_activate(repo_root, force: true)
+      in ["start", ref]
+        abort "Start the checked-out branch from its worktree." unless ref == worktree_ref(repo_root).first
+        worktree_activate(repo_root)
+      in ["stop"] then worktree_stop(repo_root)
+      in ["cleanup"] | ["register", _] then worktree_cleanup
+      in ["status"] then worktree_status
+      in ["ports"] then worktree_ports
+      in ["port"] then worktree_port
+      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|ports|port|logs [args]|run -- <cmd>|doctor|cleanup}"
+        return 64
+      end
+      0
+    end
+
+    def with_state_lock
+      FileUtils.mkdir_p(state_root)
+      File.open(File.join(state_root, "lock"), "w") do |lock|
+        lock.flock(File::LOCK_EX)
+        data = state
+        result = yield(data)
+        save_state(data)
+        result
+      end
+    end
+
+    def with_worktree_lock(id)
+      directory = File.join(state_root, "worktree-locks")
+      FileUtils.mkdir_p(directory)
+      File.open(File.join(directory, id), "w") do |lock|
+        lock.flock(File::LOCK_EX)
+        yield
+      end
+    end
+
+    def worktree_identity(path)
+      git_dir, status = Open3.capture2("git", "-C", path, "rev-parse", "--absolute-git-dir")
+      abort "Not a Git worktree: #{path}" unless status.success?
+      Digest::SHA256.hexdigest(File.realpath(git_dir.strip))[0, 16]
+    end
+
+    def canonical_worktree_path(path)
+      File.join(File.realpath(File.dirname(path)), File.basename(path))
+    rescue Errno::ENOENT
+      File.expand_path(path)
+    end
+
+    def worktree_ref(path)
+      branch, status = Open3.capture2("git", "-C", path, "symbolic-ref", "--quiet", "--short", "HEAD")
+      head, head_status = Open3.capture2("git", "-C", path, "rev-parse", "HEAD")
+      abort "Worktree has no commit: #{path}" unless head_status.success?
+      [status.success? ? branch.strip : "detached-#{head.strip[0, 12]}", head.strip]
+    end
+
+    def worktree_manager(entry) = Managers.build(entry.fetch("configuration"))
+
+    def current_worktree_entry(data, path = repo_root)
+      id = worktree_identity(path)
+      record = data.fetch("worktrees", {})[id]
+      return [nil, nil] unless record
+
+      [record, record.fetch("environments", {})[record["current"]]]
+    end
+
+    def worktree_port_for(id, data, manager, base: preferred_port)
+      reserved = data.fetch("worktrees", {}).values.map { |record| record["port"] }
+      (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 worktree_activate(path, force: false)
+      path = File.realpath(path)
+      id = worktree_identity(path)
+      with_worktree_lock(id) do
+        ref, head = worktree_ref(path)
+        config = configuration(root: path)
+        manager = Managers.build(config)
+        abort "#{config.fetch('manager')} is unavailable." unless manager.available?
+
+        existing = nil
+        with_state_lock do |data|
+          record = data.fetch("worktrees", {})[id]
+          existing = record&.fetch("environments", {})&.[](ref)
+        end
+        return if existing && !force && existing["snapshot"] == path && existing["head"] == head && existing["status"] == "running"
+
+        previous = nil
+        port = nil
+        with_state_lock do |data|
+          record = (data["worktrees"] ||= {})[id] ||= { "path" => path, "environments" => {} }
+          previous = record.fetch("environments")[record["current"]] if record["current"] && record["current"] != ref
+          port = record["port"] ||= worktree_port_for(id, data, manager, base: config.fetch("preferred_port"))
+          record["path"] = path
+        end
+        if previous
+          abort "Could not stop previous environment for #{path}." unless worktree_manager(previous).stop(previous)
+          with_state_lock do |data|
+            data.fetch("worktrees").fetch(id).fetch("environments").fetch(previous.fetch("ref"))["status"] = "stopped"
+          end
+        end
+        abort "Could not reset environment for #{path}." if existing && !worktree_manager(existing).reset(existing)
+
+        project = "brunch-#{id[0, 12]}-#{Digest::SHA256.hexdigest(ref)[0, 12]}"
+        control = File.join(state_root, "controls", project)
+        archive_ref(head, control)
+        compose_file = config.fetch("compose_file")
+        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)
+        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" }
+        with_state_lock do |data|
+          record = data.fetch("worktrees").fetch(id)
+          record.fetch("environments")[ref] = entry
+          record["current"] = ref
+        end
+        abort "Could not create environment for #{path}." unless manager.create(entry)
+        abort "Could not start environment for #{path}." unless manager.start(entry)
+        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}"
+      end
+    end
+
+    def worktree_stop(path)
+      id = worktree_identity(path)
+      with_worktree_lock(id) do
+        with_state_lock do |data|
+          _record, entry = current_worktree_entry(data, path)
+          raise CLI::OperationError, "No Brunch environment in this worktree." unless entry
+
+          abort "Could not stop #{entry.fetch('project')}." unless worktree_manager(entry).stop(entry)
+          entry["status"] = "stopped"
+          puts "Stopped #{entry.fetch('project')}."
+        end
+      end
+    end
+
+    def worktree_remove(path)
+      path = canonical_worktree_path(path)
+      data = state
+      id, = data.fetch("worktrees", {}).find { |_key, record| record["path"] == path }
+      return unless id
+
+      with_worktree_lock(id) do
+        record = state.fetch("worktrees").fetch(id)
+        record.fetch("environments").each do |ref, entry|
+          abort "Could not remove environment #{ref}." unless worktree_manager(entry).remove(entry)
+        end
+        with_state_lock { |locked| locked.fetch("worktrees").delete(id) }
+        puts "Removed Brunch environments for #{path}."
+      end
+    end
+
+    def worktree_move(old_path, new_path)
+      old_path = canonical_worktree_path(old_path)
+      new_path = File.realpath(new_path)
+      data = state
+      id, = data.fetch("worktrees", {}).find { |_key, record| record["path"] == old_path }
+      return worktree_activate(new_path) unless id
+
+      with_worktree_lock(id) do
+        record = state.fetch("worktrees").fetch(id)
+        record.fetch("environments").each_value do |entry|
+          next unless entry["status"] == "running"
+
+          abort "Could not stop environment during worktree move." unless worktree_manager(entry).stop(entry)
+        end
+        with_state_lock do |locked|
+          updated = locked.fetch("worktrees").fetch(id)
+          updated["path"] = new_path
+          updated.fetch("environments").each_value do |entry|
+            entry["snapshot"] = new_path
+            entry["status"] = "stopped"
+          end
+        end
+      end
+      worktree_activate(new_path, force: true)
+    end
+
+    def worktree_repair(path)
+      path = File.realpath(path)
+      record = state.fetch("worktrees", {})[worktree_identity(path)]
+      if record && record.fetch("path") != path
+        worktree_move(record.fetch("path"), path)
+      else
+        worktree_activate(path)
+      end
+    end
+
+    def worktree_paths
+      output, status = Open3.capture2("git", "worktree", "list", "--porcelain", "-z")
+      abort "Could not list Git worktrees." unless status.success?
+      output.split("\0").filter_map do |field|
+        canonical_worktree_path(field.delete_prefix("worktree ")) if field.start_with?("worktree ")
+      end
+    end
+
+    def worktree_cleanup
+      paths = worktree_paths
+      identities = paths.each_with_object({}) do |path, result|
+        result[worktree_identity(path)] = path if File.directory?(path)
+      end
+      data = state
+      data.fetch("worktrees", {}).each do |id, record|
+        path = record.fetch("path")
+        if identities[id] && identities[id] != path
+          worktree_move(path, identities[id])
+        elsif !paths.include?(path)
+          worktree_remove(path)
+        end
+      end
+    end
+
+    def worktree_status
+      data = state
+      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')}"
+    end
+
+    def worktree_ports
+      data = state
+      current_id = worktree_identity(repo_root)
+      data.fetch("worktrees", {}).sort_by { |_id, record| record.fetch("path") }.each do |id, record|
+        entry = record.fetch("environments", {})[record["current"]]
+        next unless entry
+
+        marker = id == current_id ? color("●", 32) : "○"
+        name = id == current_id ? color(entry.fetch("ref"), 32) : entry.fetch("ref")
+        puts "#{marker} #{name}  #{record.fetch('port')}  #{record.fetch('path')}"
+      end
+    end
+
+    def worktree_port
+      record, = current_worktree_entry(state)
+      raise CLI::OperationError, "No Brunch environment in this worktree." unless record
+
+      puts record.fetch("port")
+    end
+
+    def worktree_logs(arguments)
+      _record, entry = current_worktree_entry(state)
+      raise CLI::OperationError, "No Brunch environment in this worktree." unless entry
+
+      worktree_manager(entry).logs(entry, *arguments)
+    end
+
+    def worktree_run(command)
+      _record, entry = current_worktree_entry(state)
+      raise CLI::OperationError, "No Brunch environment in this worktree." unless entry
+
+      abort "Command failed: #{command.join(' ')}" unless system(worktree_manager(entry).environment(entry), *command,
+                                                                 chdir: entry.fetch("snapshot"))
+    end
+
+    def worktree_doctor
+      data = state
+      ports = data.fetch("worktrees", {}).values.map { |record| record["port"] }
+      paths = worktree_paths
+      hooks_dir = git_output("rev-parse", "--git-path", "hooks")
+      checks = {
+        "Git worktree" => !worktree_identity(repo_root).empty?,
+        "git-hooks-ext" => system("ghe", "--version", out: File::NULL, err: File::NULL),
+        "Brunch hooks" => Hooks::EVENTS.all? do |event|
+          path = File.join(hooks_dir, event)
+          File.file?(path) && File.read(path).include?("Brunch::Hooks.dispatch")
+        end,
+        "Configuration" => !configuration.nil?,
+        "Manager" => Managers.build(configuration).available?,
+        "Unique ports" => ports.uniq.size == ports.size,
+        "Port range" => ports.all? { |port| CLI::PORT_RANGE.cover?(port) },
+        "Git worktree paths" => data.fetch("worktrees", {}).values.all? do |record|
+          paths.include?(record.fetch("path"))
+        end
+      }
+      checks.each { |name, passed| puts "#{passed ? 'OK' : 'FAIL'} #{name}" }
+      abort "Brunch doctor found problems." unless checks.values.all?
+    end
+  end
+end

data/lib/brunch.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "brunch/version"
+require_relative "brunch/managers"
+require_relative "brunch/worktree_mode"
+require_relative "brunch/cli"
+require_relative "brunch/hooks"

metadata

@@ -1,27 +1,109 @@
 --- !ruby/object:Gem::Specification
 name: brunch
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.8.0
 platform: ruby
 authors:
 - Maciej Ciemborowicz
-autorequire: 
-bindir: bin
+bindir: exe
 cert_chain: []
-date: 2018-07-25 00:00:00.000000000 Z
-dependencies: []
-description: 
-email: no@email.com
-executables: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: reek
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.5'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.75'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.75'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: Brunch uses Git hooks and git-hooks-ext to run isolated branch environments
+  in parallel worktrees through Docker Compose or custom managers.
+executables:
+- brunch
 extensions: []
 extra_rdoc_files: []
-files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- brunch.webp
+- exe/brunch
+- lib/brunch.rb
+- lib/brunch/cli.rb
+- lib/brunch/hooks.rb
+- lib/brunch/managers.rb
+- lib/brunch/version.rb
+- lib/brunch/worktree_mode.rb
 homepage: https://github.com/ciembor/brunch
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/ciembor/brunch.git
-post_install_message: 
+  homepage_uri: https://github.com/ciembor/brunch
+  changelog_uri: https://github.com/ciembor/brunch/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -29,16 +111,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.2
-signing_key: 
+rubygems_version: 3.6.9
 specification_version: 4
-summary: Separate database for each git branch.
+summary: Isolated development environments for Git branches and worktrees
 test_files: []