brunch 0.0.1 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 0446f4c84c8e70a7178c9de33468d90d7747c12b
-  data.tar.gz: 4f08030c58640bbbeea3a2078083bca77744461e
+SHA256:
+  metadata.gz: 318ff646dd610a9647612d8ea0fcc446e5122215f4517d665fc639b5bfca740d
+  data.tar.gz: e4aeddec12c82d9b0d33caddf6a366840e3db8badd45fec4114f57bd034c3d86
 SHA512:
-  metadata.gz: 0dc5753a95e229da0bf221648a291b8c745194e4798674fa3ab377f8cce5d7969843780791db8dd12d0767b4f6001ed5ac0f3a58c6b9c12abdeb7e9ea5217ff2
-  data.tar.gz: 2e2a24eb7ce8c920cef40c55bc744c0399c81653872eca813aa25aa395a6ca86ef42abf0f022123a7bd9e4a876a6528409121ff39954ebe742af04210d185202
+  metadata.gz: d334e9cc379f39f4866626e8801adbdc9cbe8aace2d0249b8b4a6a81020b34ec35eca8b8dcf742622e06545d58086966ed087784b077460bdc7e56e5ec150f1c
+  data.tar.gz: b34f7f1baf8dbbf6a56669ccc310846eab6aa23d891fa05e4adbe541e1ab1ccea954bfdb46c087fba7a47e3601f45f967efb1de8ff93d7678cb361abaec6eb1c

data/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+## Unreleased
+
+## 0.8.1 - 2026-09-29
+
+- Reorganize the README into a step-by-step guide for branches, parallel
+  worktrees, managers, and everyday commands.
+
+## 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,355 @@
+# Brunch
+
+![Brunch — container per branch and worktree](brunch.webp)
+
+Brunch runs isolated development environments for Git branches and worktrees.
+
+Each branch gets its own environment. With Compose, that means a separate project, network, containers, and named volumes. Branches checked out in the same worktree share its host port, while additional worktrees get different ports and can run in parallel.
+
+Docker Compose is the default manager. Podman Compose, local processes, and custom project commands are also supported.
+
+## Requirements
+
+- Ruby 3.1+
+- Git 2.28+
+- Docker Compose, Podman Compose, or another supported manager
+- [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 available on your `PATH`, then install Brunch:
+
+```bash
+gem install brunch
+```
+
+Inside each repository you want Brunch to manage:
+
+```bash
+brunch install
+```
+
+Brunch installs its hooks through `git-hooks-ext` and will not overwrite hooks owned by another tool.
+
+## Configuration
+
+Add `brunch.yml` to the repository root.
+
+For Docker Compose:
+
+```yaml
+compose_file: compose.yaml
+```
+
+Expose the application through `BRUNCH_PORT`:
+
+```yaml
+services:
+  web:
+    ports:
+      - "127.0.0.1:${BRUNCH_PORT}:3000"
+```
+
+The first activated worktree prefers port `3000`. Additional worktrees receive another free port.
+
+To prefer a different starting port:
+
+```yaml
+preferred_port: 4000
+```
+
+Port assignments are persisted per worktree in `.git/brunch/state.json`.
+
+## Getting started
+
+Commit `brunch.yml` and the application configuration first. The repository must contain at least one commit.
+
+Then run:
+
+```bash
+brunch install
+brunch doctor
+brunch activate
+brunch status
+```
+
+`brunch activate` starts the environment for the currently checked-out branch.
+
+To print only the current worktree's port:
+
+```bash
+brunch port
+```
+
+Open the application on the printed port, for example:
+
+```text
+http://127.0.0.1:3000
+```
+
+With Compose, the application must listen on the container port mapped in the Compose file.
+
+## Branch switching
+
+Once the hooks are installed, normal Git branch switches automatically stop the previous branch environment and start the new one:
+
+```bash
+git switch -c feature/login
+git switch main
+```
+
+Branches checked out in the same worktree reuse that worktree's host port.
+
+With Compose, each branch keeps its own Compose project and named volumes, so persistent resources remain isolated between branches.
+
+To manually start the environment after `brunch stop`:
+
+```bash
+brunch activate
+```
+
+To rebuild and restart it:
+
+```bash
+brunch restart
+```
+
+Compose builds use files from the live worktree, including uncommitted changes.
+
+If you want source edits to appear in an already running container without rebuilding, configure a bind mount or another reload mechanism in your Compose setup.
+
+## Parallel worktrees
+
+Additional worktrees run independently on different host ports.
+
+Create them with `git-hooks-ext`:
+
+```bash
+ghe worktree add -b feature-a ../feature-a
+ghe worktree add -b feature-b ../feature-b
+```
+
+Then:
+
+```bash
+cd ../feature-a
+
+brunch port
+brunch ports
+```
+
+`brunch port` prints the current worktree's port.
+
+`brunch ports` lists ports assigned to all worktrees.
+
+Switching branches inside one worktree does not affect environments running in other worktrees.
+
+If you create a worktree with plain Git:
+
+```bash
+git worktree add -b feature-c ../feature-c
+```
+
+activate Brunch manually inside it:
+
+```bash
+cd ../feature-c
+brunch activate
+```
+
+After moving or removing worktrees with plain Git, run:
+
+```bash
+brunch cleanup
+```
+
+Brunch never deletes the worktree source directory.
+
+## Managers
+
+### Docker Compose
+
+Docker Compose is the default manager:
+
+```yaml
+compose_file: compose.yaml
+```
+
+### Podman Compose
+
+Podman Compose uses the same Compose file contract:
+
+```yaml
+manager: podman_compose
+compose_file: compose.yaml
+```
+
+### Local process
+
+Use `local_process` for a development command such as `bin/dev`:
+
+```yaml
+manager: local_process
+command: bin/dev
+```
+
+Brunch starts and stops the process together with the branch environment and stores its output under `.git/brunch/controls`.
+
+### Custom commands
+
+Use the `command` manager to integrate Brunch with project-specific tooling:
+
+```yaml
+manager: command
+commands:
+  create: bin/environment create
+  start: bin/environment start
+  stop: bin/environment stop
+  remove: bin/environment remove
+```
+
+Brunch runs these commands from the live worktree with:
+
+```text
+BRUNCH_REF
+BRUNCH_PORT
+BRUNCH_PROJECT
+BRUNCH_SNAPSHOT
+```
+
+`BRUNCH_SNAPSHOT` points to the live worktree for compatibility with manager adapters.
+
+`create` is optional.
+
+`start` must return after launching the environment.
+
+`stop` is called when switching away from the active branch.
+
+`remove` is called when the corresponding worktree environment is deleted and should remove manager-owned persistent resources.
+
+Optional commands:
+
+```yaml
+commands:
+  status: bin/environment status
+  health: bin/environment health
+  logs: bin/environment logs
+```
+
+These power the corresponding Brunch operations.
+
+## Worktree lifecycle
+
+A branch checkout stops the previous environment in that worktree and starts the new one on the same host port.
+
+Other worktrees continue running.
+
+Removing a worktree removes its Brunch environments. Brunch keeps the information needed to shut down manager resources under `.git/brunch/controls`, so cleanup can still run after the worktree itself is gone.
+
+If a custom `remove` command depends on project files, those files must be committed because cleanup after worktree removal uses the last committed state.
+
+`brunch cleanup` removes environments belonging to worktrees that no longer exist.
+
+Git does not expose every branch deletion workflow reliably to hooks, so stopped branch environments may remain until their worktree is removed.
+
+## Commands
+
+```bash
+brunch install
+```
+
+Install Brunch hooks for the repository.
+
+```bash
+brunch activate
+```
+
+Start the environment for the current branch.
+
+```bash
+brunch status
+```
+
+Show the current environment, manager status, and port.
+
+```bash
+brunch port
+```
+
+Print the current worktree's port.
+
+```bash
+brunch ports
+```
+
+List ports assigned to all worktrees.
+
+```bash
+brunch stop
+```
+
+Stop the active environment without removing it.
+
+```bash
+brunch restart
+```
+
+Recreate and start the active environment.
+
+```bash
+brunch logs
+brunch logs --follow
+```
+
+Show environment logs.
+
+```bash
+brunch run -- bin/rails console
+```
+
+Run a command on the host from the live worktree.
+
+```bash
+brunch doctor
+```
+
+Check Git, installed hooks, configuration, manager availability, and ports.
+
+```bash
+brunch cleanup
+```
+
+Remove environments belonging to deleted worktrees.
+
+## Upgrading from older configurations
+
+Before upgrading from an older branch-only configuration, stop its running environment and clean up its legacy state.
+
+Brunch will not reinterpret an existing non-empty branch-only state as worktree state.
+
+## Development
+
+```bash
+bundle install
+bin/install-pre-commit
+bundle exec rake quality
+gem build brunch.gemspec
+```
+
+Run container integration tests with Docker Compose:
+
+```bash
+BRUNCH_INTEGRATION_MANAGER=docker_compose bundle exec rake test
+```
+
+Or Podman Compose:
+
+```bash
+BRUNCH_INTEGRATION_MANAGER=podman_compose bundle exec rake test
+```
+
+Without `BRUNCH_INTEGRATION_MANAGER`, container integration 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 for `lib/**/*.rb`.
+
+If RuboCop modifies a file, review and stage the changes 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