bake-gem 0.11.1 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6696fea309e0e6f44c0907ec7f989ba035ed1894f8d1451e748a7dc643f59a68
-  data.tar.gz: 6ab62d3b7d148130eb2b9812f57750321efb6cb8cc50f5f50fa9fd8306ae2f56
+  metadata.gz: 7b25175c2d6cf7d1761d1e907fcd305627d7d8aeb394877b02133ebb4b04ce83
+  data.tar.gz: dc59a56876e85654723fa2b1e600078f99f9c70b34b4e7538796788f9d34f3c9
 SHA512:
-  metadata.gz: f77553e1d121cc08a9ee60bd8e1baaa8a64f767039f10339f40571abf41c20f024192c612d72143f08aedde596f2ac171bbda93e5c1ca5ca531da69bb640d247
-  data.tar.gz: ecabafafebf96384fae2a85dfb4d8421bd592617105aba85a7e14e2fe34a2853abb4f9916cdd70a66459bb39787a3dc7c1a40d97aeb63e6a5d6112e105e1c9ad
+  metadata.gz: 53bbab1dc7b1ce0ee92b176624a9a0032ffebd2a482c13477187c6e03965871f1f95c132e84aad5f0361930dc32cd3f2827df5e36cdb5a4e8f405ba8faa17198
+  data.tar.gz: 6af3f18bee98f04af4c700c4282873eec88d927945e43176c9a24cff5dbc78eb3f88097d817e43373243c51894c41c4a41d855a949a343d827ef9ecd908fca5b

data/agent.md

@@ -0,0 +1,61 @@
+# Agent
+
+## Context
+
+This section provides links to documentation from installed packages. It is automatically generated and may be updated by running `bake agent:context:install`.
+
+**Important:** Before performing any code, documentation, or analysis tasks, always read and apply the full content of any relevant documentation referenced in the following sections. These context files contain authoritative standards and best practices for documentation, code style, and project-specific workflows. **Do not proceed with any actions until you have read and incorporated the guidance from relevant context files.**
+
+**Setup Instructions:** If the referenced files are not present or if dependencies have been updated, run `bake agent:context:install` to install the latest context files.
+
+### agent-context
+
+Install and manage context files from Ruby gems.
+
+#### [Getting Started](.context/agent-context/getting-started.md)
+
+This guide explains how to use `agent-context`, a tool for discovering and installing contextual information from Ruby gems to help AI agents.
+
+### decode
+
+Code analysis for documentation generation.
+
+#### [Getting Started with Decode](.context/decode/getting-started.md)
+
+The Decode gem provides programmatic access to Ruby code structure and metadata. It can parse Ruby files and extract definitions, comments, and documentation pragmas, enabling code analysis, documentation generation, and other programmatic manipulations of Ruby codebases.
+
+#### [Documentation Coverage](.context/decode/coverage.md)
+
+This guide explains how to test and monitor documentation coverage in your Ruby projects using the Decode gem's built-in bake tasks.
+
+#### [Ruby Documentation](.context/decode/ruby-documentation.md)
+
+This guide covers documentation practices and pragmas supported by the Decode gem for documenting Ruby code. These pragmas provide structured documentation that can be parsed and used to generate API documentation and achieve complete documentation coverage.
+
+#### [Setting Up RBS Types and Steep Type Checking for Ruby Gems](.context/decode/types.md)
+
+This guide covers the process for establishing robust type checking in Ruby gems using RBS and Steep, focusing on automated generation from source documentation and proper validation.
+
+### sus
+
+A fast and scalable test runner.
+
+#### [Using Sus Testing Framework](.context/sus/usage.md)
+
+Sus is a modern Ruby testing framework that provides a clean, BDD-style syntax for writing tests. It's designed to be fast, simple, and expressive.
+
+#### [Mocking](.context/sus/mocking.md)
+
+There are two types of mocking in sus: `receive` and `mock`. The `receive` matcher is a subset of full mocking and is used to set expectations on method calls, while `mock` can be used to replace method implementations or set up more complex behavior.
+
+#### [Shared Test Behaviors and Fixtures](.context/sus/shared.md)
+
+Sus provides shared test contexts which can be used to define common behaviours or tests that can be reused across one or more test files.
+
+### sus-fixtures-console
+
+Test fixtures for capturing Console output.
+
+#### [Getting Started](.context/sus-fixtures-console/getting-started.md)
+
+This guide explains how to use the `Sus::Fixtures::Console` gem to redirect console logging output during tests.

data/bake/gem/release/branch.rb

@@ -3,10 +3,6 @@
 # Released under the MIT License.
 # Copyright, 2021-2025, by Samuel Williams.
 
-require_relative "../../../lib/bake/gem/shell"
-
-include Bake::Gem::Shell
-
 # Increment the patch number of the current version.
 def patch
 	commit([nil, nil, 1], message: "Bump patch version.")
@@ -36,9 +32,7 @@ def commit(bump, message: "Bump version.")
 	version_path = context.lookup("gem:release:version:increment").call(bump, message: message)
 	
 	if version_path
-		system("git", "checkout", "-b", "release-v#{gemspec.version}")
-		system("git", "add", version_path, chdir: context.root)
-		system("git", "commit", "-m", message, chdir: context.root)
+		branch_name = helper.create_release_branch(version_path, message: message)
 	else
 		raise "Could not find version number!"
 	end
@@ -46,6 +40,6 @@ def commit(bump, message: "Bump version.")
 	return {
 		version: gemspec.version,
 		version_path: version_path,
-		branch: "release-v#{gemspec.version}",
+		branch: branch_name,
 	}
 end

data/bake/gem/release/version.rb

@@ -3,10 +3,6 @@
 # Released under the MIT License.
 # Copyright, 2021-2025, by Samuel Williams.
 
-require_relative "../../../lib/bake/gem/shell"
-
-include Bake::Gem::Shell
-
 # Increment the patch number of the current version.
 def patch
 	commit([nil, nil, 1], message: "Bump patch version.")
@@ -59,8 +55,7 @@ def commit(bump, message: "Bump version.")
 	version_path = increment(bump, message: message)
 	
 	if version_path
-		system("git", "add", "--all", chdir: context.root)
-		system("git", "commit", "-m", message, chdir: context.root)
+		helper.commit_version_changes(message: message)
 	else
 		raise "Could not find version number!"
 	end

data/bake/gem/release.rb

@@ -0,0 +1,35 @@
+
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2021-2025, by Samuel Williams.
+
+# Bump the patch version and release the gem in one command.
+# @parameter tag [Boolean] Whether to tag the release.
+def patch(tag: true)
+	version_commit_task = context.lookup("gem:release:version:commit")
+	version_commit_task.call([nil, nil, 1], message: "Bump patch version.")
+	
+	release_task = context.lookup("gem:release")
+	release_task.call(tag: tag)
+end
+
+# Bump the minor version and release the gem in one command.
+# @parameter tag [Boolean] Whether to tag the release.
+def minor(tag: true)
+	version_commit_task = context.lookup("gem:release:version:commit")
+	version_commit_task.call([nil, 1, 0], message: "Bump minor version.")
+	
+	release_task = context.lookup("gem:release")
+	release_task.call(tag: tag)
+end
+
+# Bump the major version and release the gem in one command.
+# @parameter tag [Boolean] Whether to tag the release.
+def major(tag: true)
+	version_commit_task = context.lookup("gem:release:version:commit")
+	version_commit_task.call([1, 0, 0], message: "Bump major version.")
+	
+	release_task = context.lookup("gem:release")
+	release_task.call(tag: tag)
+end

data/bake/gem.rb

@@ -3,14 +3,13 @@
 # Released under the MIT License.
 # Copyright, 2021-2025, by Samuel Williams.
 
-require_relative "../lib/bake/gem/helper"
-require_relative "../lib/bake/gem/shell"
-
-include Bake::Gem::Shell
-
+# Initialize the gem context with helper for gem operations.
+# @parameter context [Bake::Context] The bake execution context.
 def initialize(context)
 	super(context)
 	
+	require_relative "../lib/bake/gem/helper"
+	
 	@helper = Bake::Gem::Helper.new(context.root)
 end
 
@@ -52,44 +51,24 @@ def release(tag: true)
 	@helper.guard_clean
 	
 	version = @helper.gemspec.version
+	current_branch = @helper.current_branch
 	
-	if tag
-		name = "v#{version}"
-		system("git", "fetch", "--all", "--tags")
-		system("git", "tag", name)
-	end
+	tag_name = @helper.create_release_tag(tag: tag, version: version)
 	
 	begin
-		path = @helper.build_gem
+		path = @helper.build_gem_in_worktree
 		@helper.push_gem(path: path)
 	rescue => error
-		system("git", "tag", "--delete", name)
+		@helper.delete_git_tag(tag_name) if tag_name
 		raise
 	end
 	
-	# If we are on a branch, push, otherwise just push the tags (assuming shallow checkout):
-	if current_branch
-		system("git", "push")
-	end
-	
-	system("git", "push", "--tags")
+	@helper.push_release(current_branch: current_branch)
 	
 	return {
 		name: @helper.gemspec.name,
 		version: @helper.gemspec.version,
 		package_path: path,
-		tag: name,
+		tag: tag_name,
 	}
 end
-
-private
-
-# Figure out if there is a current branch, if not, return `nil`.
-def current_branch
-	# We originally used this but it is not supported by older versions of git.
-	# readlines("git", "branch", "--show-current").first&.chomp
-	
-	readlines("git", "symbolic-ref", "--short", "--quiet", "HEAD").first&.chomp
-rescue
-	nil
-end

data/context/getting-started.md

@@ -0,0 +1,228 @@
+# Getting Started
+
+This guide explains how to use `bake-gem` to release gems safely and efficiently.
+
+## Installation
+
+Add the `bake-gem` gem to your project:
+
+``` bash
+$ bundle add bake-gem
+```
+
+You may prefer to keep it in a separate `maintenance` group:
+
+``` ruby
+group :maintenance, optional: true do
+	gem "bake-gem"
+end
+```
+
+## Usage
+
+Before using `bake-gem`, ensure you have:
+
+1. A properly configured `gemspec` file in your project root
+2. A clean git repository (no uncommitted changes)
+3. Your gem's version file (typically `lib/your_gem/version.rb`)
+4. RubyGems credentials configured for publishing
+
+### Local Release Process
+
+The most typical process for releasing a gem locally:
+
+``` bash
+$ bake gem:release:version:patch gem:release
+```
+
+This command will:
+1. **Guard against consecutive version bumps** - Prevents accidentally bumping version twice
+2. **Check repository cleanliness** - Ensures no uncommitted changes
+3. **Increment the version** - Updates your version file (patch/minor/major)
+4. **Commit the version change** - Creates a commit with the version bump
+5. **Build the gem in a clean worktree** - Isolates the build process
+6. **Push to RubyGems** - Publishes your gem
+7. **Create and push git tags** - Tags the release
+
+### Version Increment Options
+
+Choose the appropriate version increment:
+
+``` bash
+# For bug fixes (1.0.0 -> 1.0.1)
+$ bake gem:release:version:patch gem:release
+
+# For new features (1.0.0 -> 1.1.0)
+$ bake gem:release:version:minor gem:release
+
+# For breaking changes (1.0.0 -> 2.0.0)
+$ bake gem:release:version:major gem:release
+```
+
+## Advanced Workflows
+
+### Automated CI/CD Pipeline
+
+For releasing gems via automated pipelines, use a two-step process:
+
+#### Step 1: Create Release Branch (Locally)
+
+``` bash
+# Create a release branch with version bump
+$ bake gem:release:branch:patch  # or minor/major
+```
+
+This will:
+- Create a new branch named `releases/v[new-version]`
+- Bump the gem version
+- Commit the version change
+- Push the branch to origin
+
+#### Step 2: Release from CI (After Merge)
+
+Once the release branch is merged into main:
+
+``` bash
+$ export RUBYGEMS_HOST=https://rubygems.org
+$ export GEM_HOST_API_KEY=your_api_key
+
+$ bake gem:release
+```
+
+### Individual Commands
+
+You can also run individual steps:
+
+``` bash
+# Just build the gem
+$ bake gem:build
+
+# Install the gem locally for testing
+$ bake gem:install
+
+# List files that will be included in the gem
+$ bake gem:files
+
+# Build without signing
+$ bake gem:build signing_key=false
+```
+
+## Safety Features
+
+`bake-gem` includes several safety features:
+
+### Consecutive Version Bump Prevention
+The tool automatically prevents consecutive version bumps by checking the last commit message. If the last commit was already a version bump (e.g., "Bump patch version."), it will raise an error.
+
+### Clean Worktree Building
+Gems are built in isolated git worktrees to ensure the build environment exactly matches your committed code, preventing issues with uncommitted changes affecting the build.
+
+### Repository Cleanliness Check
+Before any release operation, the tool ensures your repository has no uncommitted changes.
+
+## Configuration
+
+### Gem Signing
+
+To sign your gems, ensure your gemspec includes:
+
+``` ruby
+spec.signing_key = "path/to/private_key.pem"
+spec.cert_chain = ["path/to/certificate.pem"]
+```
+
+Or disable signing explicitly:
+
+``` bash
+$ bake gem:build signing_key=false
+```
+
+### RubyGems Configuration
+
+For automated releases, set these environment variables:
+
+``` bash
+export RUBYGEMS_HOST=https://rubygems.org  # or your private gem server
+export GEM_HOST_API_KEY=your_api_key
+```
+
+## Examples
+
+### Complete Release Example
+
+``` bash
+# 1. Ensure clean repository
+$ git status
+
+# 2. Run tests
+$ bundle exec rake test  # or your test command
+
+# 3. Release with patch version increment
+$ bake gem:release:version:patch gem:release
+
+# Output:
+# Updated version: v1.2.4
+# Successfully built RubyGem
+# Name: my-gem
+# Version: 1.2.4
+# File: my-gem-1.2.4.gem
+# Pushing gem to https://rubygems.org...
+# Tagged: v1.2.4
+```
+
+### Branch-based Release Example
+
+``` bash
+# Create release branch
+$ bake gem:release:branch:minor
+# Creates branch: releases/v1.3.0
+# Commits version bump
+# Pushes branch
+
+# After code review and merge:
+$ git checkout main
+$ git pull
+$ bake gem:release
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**"Repository has uncommitted changes"**
+```bash
+$ git status  # Check what's uncommitted
+$ git add .   # Stage changes
+$ git commit -m "Prepare for release"  # Or stash them
+```
+
+**"Last commit appears to be a version bump"**
+```bash
+# Make some changes first, or use --force if intentional
+$ git log -1  # Check the last commit message
+```
+
+**"Multiple gemspecs found"**
+```bash
+# Specify which gemspec to use or remove extras
+$ ls *.gemspec
+```
+
+**"No version file found"**
+```bash
+# Ensure your version file follows the expected pattern:
+# VERSION = "1.0.0"
+```
+
+### Getting Help
+
+List all available gem commands:
+``` bash
+$ bake list | grep gem
+```
+
+Get help for specific commands:
+``` bash
+$ bake gem:release --help
+```
+````

data/context/index.yaml

@@ -0,0 +1,13 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: Release management for Ruby gems.
+metadata:
+  documentation_uri: https://ioquatix.github.io/bake-gem/
+  funding_uri: https://github.com/sponsors/ioquatix/
+  source_code_uri: https://github.com/ioquatix/bake-gem.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use `bake-gem` to release gems safely and
+    efficiently.

data/lib/bake/gem/helper.rb

@@ -6,11 +6,13 @@
 require "rubygems"
 require "rubygems/package"
 require "fileutils"
+require "tmpdir"
 
 require_relative "shell"
 
 module Bake
 	module Gem
+		# Represents a gem version with support for parsing and incrementing version numbers.
 		class Version
 			LINE_PATTERN = /VERSION = ['"](?<version>(?<parts>\d+\.\d+\.\d+)(-(?<suffix>.*?))?)['"]/
 			
@@ -28,11 +30,16 @@ module Bake
 				end
 			end
 			
+			# Initialize a new version with the given parts and optional suffix.
+			# @parameter parts [Array(Integer)] The version number parts (e.g., [1, 2, 3] for "1.2.3").
+			# @parameter suffix [String | Nil] The optional version suffix (e.g., "alpha", "beta").
 			def initialize(parts, suffix)
 				@parts = parts
 				@suffix = suffix
 			end
 			
+			# Check if this version represents a release version.
+			# @returns [Boolean] True if the version has no suffix, indicating it's a release version.
 			def release?
 				@suffix.nil?
 			end
@@ -51,10 +58,13 @@ module Bake
 				"v#{join}"
 			end
 			
+			# Increment the version according to the provided bump specification.
+			# @parameter bump [Array(Integer | Nil)] Array specifying how to increment each version part.
+			# @returns [Version] Self, for method chaining.
 			def increment(bump)
 				bump.each_with_index do |increment, index|
 					if index > @parts.size
-						@suffix = bump[index..-1].join(".")
+						@suffix = bump[index..].join(".")
 						break
 					end
 					
@@ -63,30 +73,49 @@ module Bake
 					elsif increment == 0
 						@parts[index] = 0
 					end
+					# If increment is nil, we don't change that part of the version
 				end
 				
 				return self
 			end
 		end
 		
+		# Helper class for performing gem-related operations like building, installing, and publishing gems.
 		class Helper
 			include Shell
 			
+			# Initialize a new helper with the specified root directory and optional gemspec.
+			# @parameter root [String] The root directory of the gem project.
+			# @parameter gemspec [Gem::Specification | Nil] The gemspec to use, or nil to find it automatically.
 			def initialize(root = Dir.pwd, gemspec: nil)
 				@root = root
 				@gemspec = gemspec || find_gemspec
 			end
 			
+			# @attribute [String] The root directory of the gem project.
 			attr :root
+			
+			# @attribute [Gem::Specification] The gemspec for the gem.
 			attr :gemspec
 			
+			# Find the path to the version.rb file in the gem.
+			# @returns [String | Nil] The path to the version file, or nil if not found.
 			def version_path
-				@gemspec&.files.grep(/lib(.*?)\/version.rb/).first
+				if @gemspec
+					@gemspec.files.grep(/lib(.*?)\/version.rb/).first
+				end
 			end
 			
+			# Update the version number in the version file according to the bump specification.
+			# @parameter bump [Array(Integer)] Array specifying how to increment each version part.
+			# @parameter version_path [String] The path to the version file.
+			# @returns [String | Boolean] The path to the version file if updated, or false if no version file found.
 			def update_version(bump, version_path = self.version_path)
 				return false unless version_path
 				
+				# Guard against consecutive version bumps
+				guard_last_commit_not_version_bump
+				
 				lines = File.readlines(version_path)
 				new_version = nil
 				
@@ -107,6 +136,9 @@ module Bake
 				end
 			end
 			
+			# Verify that the repository has no uncommitted changes.
+			# @returns [Boolean] True if the repository is clean.
+			# @raises [RuntimeError] If there are uncommitted changes in the repository.
 			def guard_clean
 				lines = readlines("git", "status", "--porcelain", chdir: @root)
 				
@@ -117,14 +149,37 @@ module Bake
 				return true
 			end
 			
+			# Verify that the last commit was not a version bump.
+			# @returns [Boolean] True if the last commit was not a version bump.
+			# @raises [RuntimeError] If the last commit was a version bump.
+			def guard_last_commit_not_version_bump
+				# Get the last commit message:
+				begin
+					last_commit_message = readlines("git", "log", "-1", "--pretty=format:%s", chdir: @root).first&.strip
+				rescue CommandExecutionError => error
+					# If git log fails (e.g., no commits yet), skip the check:
+					if error.exit_code == 128
+						return true
+					else
+						raise
+					end
+				end
+				
+				if last_commit_message && last_commit_message.match?(/^Bump (patch|minor|major|version)( version)?\.?$/i)
+					raise "Last commit appears to be a version bump: #{last_commit_message.inspect}. Cannot bump version consecutively."
+				end
+				
+				return true
+			end
+			
 			# @parameter root [String] The root path for package files.
 			# @parameter signing_key [String | Nil] The signing key to use for signing the package.
 			# @returns [String] The path to the built gem package.
 			def build_gem(root: "pkg", signing_key: nil)
 				# Ensure the output directory exists:
-				FileUtils.mkdir_p("pkg")
+				FileUtils.mkdir_p(root)
 				
-				output_path = File.join("pkg", @gemspec.file_name)
+				output_path = File.join(root, @gemspec.file_name)
 				
 				if signing_key == false
 					@gemspec.signing_key = nil
@@ -137,14 +192,119 @@ module Bake
 				::Gem::Package.build(@gemspec, false, false, output_path)
 			end
 			
+			# Install the gem using the `gem install` command.
+			# @parameter arguments [Array] Additional arguments to pass to `gem install`.
+			# @parameter path [String] The path to the gem file to install.
 			def install_gem(*arguments, path: @gemspec.file_name)
 				system("gem", "install", path, *arguments)
 			end
 			
+			# Push the gem to a gem repository using the `gem push` command.
+			# @parameter arguments [Array] Additional arguments to pass to `gem push`.
+			# @parameter path [String] The path to the gem file to push.
 			def push_gem(*arguments, path: @gemspec.file_name)
 				system("gem", "push", path, *arguments)
 			end
 			
+			# Build the gem in a clean worktree for better isolation
+			# @parameter root [String] The root path for package files.
+			# @parameter signing_key [String | Nil] The signing key to use for signing the package.
+			# @returns [String] The path to the built gem package.
+			def build_gem_in_worktree(root: "pkg", signing_key: nil)
+				original_pkg_path = File.join(@root, root)
+				
+				# Create a unique temporary path for the worktree
+				timestamp = Time.now.strftime("%Y%m%d-%H%M%S-%N")
+				worktree_path = File.join(Dir.tmpdir, "bake-gem-build-#{timestamp}")
+				
+				begin
+					# Create worktree from current HEAD
+					unless system("git", "worktree", "add", worktree_path, "HEAD", chdir: @root)
+						raise "Failed to create git worktree. Make sure you have at least one commit in the repository."
+					end
+					
+					# Create helper for the worktree
+					worktree_helper = self.class.new(worktree_path)
+					
+					# Build gem directly into the target pkg directory
+					output_path = worktree_helper.build_gem(root: original_pkg_path, signing_key: signing_key)
+					
+					output_path
+				ensure
+					# Clean up the worktree
+					system("git", "worktree", "remove", worktree_path, "--force", chdir: @root)
+				end
+			end
+			
+			# Create a release branch, add the version file, and commit the changes.
+			# @parameter version_path [String] The path to the version file that was updated.
+			# @parameter message [String] The commit message to use.
+			# @returns [String] The name of the created branch.
+			def create_release_branch(version_path, message: "Bump version.")
+				branch_name = "release-v#{@gemspec.version}"
+				
+				system("git", "checkout", "-b", branch_name, chdir: @root)
+				system("git", "add", version_path, chdir: @root)
+				system("git", "commit", "-m", message, chdir: @root)
+				
+				return branch_name
+			end
+			
+			# Commit version changes to the current branch.
+			# @parameter message [String] The commit message to use.
+			def commit_version_changes(message: "Bump version.")
+				system("git", "add", "--all", chdir: @root)
+				system("git", "commit", "-m", message, chdir: @root)
+			end
+			
+			# Fetch remote tags and create a release tag for the specified version.
+			# @parameter tag [Boolean] Whether to tag the release.
+			# @parameter version [String] The version to tag.
+			# @returns [String | Nil] The tag name if created, nil otherwise.
+			def create_release_tag(tag: true, version:)
+				tag_name = nil
+				
+				if tag
+					tag_name = "v#{version}"
+					system("git", "fetch", "--all", "--tags", chdir: @root)
+					system("git", "tag", tag_name, chdir: @root)
+				end
+				
+				return tag_name
+			end
+			
+			# Delete a git tag.
+			# @parameter tag_name [String] The name of the tag to delete.
+			def delete_git_tag(tag_name)
+				system("git", "tag", "--delete", tag_name, chdir: @root)
+			end
+			
+			# Push changes and tags to the remote repository.
+			# @parameter current_branch [String | Nil] The current branch name, or nil if not on a branch.
+			def push_release(current_branch: nil)
+				# If we are on a branch, push, otherwise just push the tags (assuming shallow checkout):
+				if current_branch
+					system("git", "push", chdir: @root)
+				end
+				
+				system("git", "push", "--tags", chdir: @root)
+			end
+			
+			# Figure out if there is a current branch, if not, return `nil`.
+			# @returns [String | Nil] The current branch name, or nil if not on a branch.
+			def current_branch
+				# We originally used this but it is not supported by older versions of git.
+				# readlines("git", "branch", "--show-current").first&.chomp
+				
+				readlines("git", "symbolic-ref", "--short", "--quiet", "HEAD", chdir: @root).first&.chomp
+			rescue CommandExecutionError
+				nil
+			end
+			
+			# Find a gemspec file in the root directory.
+			# @parameter glob [String] The glob pattern to use for finding gemspec files.
+			# @returns [Gem::Specification | Nil] The loaded gemspec, or nil if none found.
+			# @raises [RuntimeError] If multiple gemspec files are found.
 			def find_gemspec(glob = "*.gemspec")
 				paths = Dir.glob(glob, base: @root).sort
 				
@@ -153,7 +313,7 @@ module Bake
 				end
 				
 				if path = paths.first
-					return ::Gem::Specification.load(path)
+					return ::Gem::Specification.load(File.expand_path(path, @root))
 				end
 			end
 		end

data/lib/bake/gem/shell.rb

@@ -8,7 +8,29 @@ require "console/event/spawn"
 
 module Bake
 	module Gem
+		# Exception raised when a command execution fails.
+		class CommandExecutionError < RuntimeError
+			def initialize(message, status)
+				super(message)
+				@status = status
+			end
+			
+			# @attribute [Process::Status] The status object of the failed command.
+			attr_reader :status
+			
+			# Helper method for convenience.
+			def exit_code
+				@status.exitstatus
+			end
+		end
+		
+		# Provides shell command execution methods with proper logging and error handling.
 		module Shell
+			# Execute a system command with logging and error handling.
+			# @parameter arguments [Array] The command and its arguments to execute.
+			# @parameter options [Hash] Additional options to pass to Process.spawn.
+			# @returns [Boolean] True if the command executed successfully.
+			# @raises [CommandExecutionError] If the command fails.
 			def system(*arguments, **options)
 				Console::Event::Spawn.for(*arguments, **options).emit(self)
 				
@@ -19,13 +41,19 @@ module Bake
 					pid, status = Process.wait2(pid) if pid
 					
 					unless status.success?
-						raise "Failed to execute #{arguments}: #{status}!"
+						raise Bake::Gem::CommandExecutionError.new("Failed to execute #{arguments}: #{status}!", status)
 					end
 					
 					return true
 				end
 			end
 			
+			# Execute a command and yield its output to a block.
+			# @parameter arguments [Array] The command and its arguments to execute.
+			# @parameter options [Hash] Additional options to pass to Process.spawn.
+			# @yields {|input| ...} The input stream from the executed command.
+			# @returns [Object] The return value of the block.
+			# @raises [CommandExecutionError] If the command fails.
 			def execute(*arguments, **options)
 				Console::Event::Spawn.for(*arguments, **options).emit(self)
 				
@@ -39,12 +67,17 @@ module Bake
 						pid, status = Process.wait2(pid)
 						
 						unless status.success?
-							raise "Failed to execute #{arguments}: #{status}!"
+							raise Bake::Gem::CommandExecutionError.new("Failed to execute #{arguments}: #{status}!", status)
 						end
 					end
 				end
 			end
 			
+			# Execute a command and return its output as an array of lines.
+			# @parameter arguments [Array] The command and its arguments to execute.
+			# @parameter options [Hash] Additional options to pass to Process.spawn.
+			# @returns [Array(String)] The output lines from the executed command.
+			# @raises [CommandExecutionError] If the command fails.
 			def readlines(*arguments, **options)
 				execute(*arguments, **options) do |output|
 					return output.readlines

data/lib/bake/gem/version.rb

@@ -5,6 +5,6 @@
 
 module Bake
 	module Gem
-		VERSION = "0.11.1"
+		VERSION = "0.12.0"
 	end
 end

data/lib/bake/gem.rb

@@ -4,3 +4,10 @@
 # Copyright, 2021-2024, by Samuel Williams.
 
 require_relative "gem/version"
+
+# @namespace
+module Bake
+	# @namespace
+	module Gem
+	end
+end

data/readme.md

@@ -8,16 +8,34 @@ Provides bake tasks for common gem release workflows.
 
 Please see the [project documentation](https://ioquatix.github.io/bake-gem/) for more details.
 
-  - [Getting Started](https://ioquatix.github.io/bake-gem/guides/getting-started/index) - This guide explains how to use `bake-gem` to release gems.
+  - [Getting Started](https://ioquatix.github.io/bake-gem/guides/getting-started/index) - This guide explains how to use `bake-gem` to release gems safely and efficiently.
 
 ## Releases
 
 Please see the [project releases](https://ioquatix.github.io/bake-gem/releases/index) for all releases.
 
+### v0.12.0
+
+  - Add `guard_last_commit_not_version_bump` method to prevent consecutive version bumps.
+  - Add `build_gem_in_worktree` method for building gems in isolated git worktrees.
+  - Improve shell command execution with better error handling and specific exit code access.
+
+### v0.11.1
+
+  - Better integration with `bake`'s default output.
+
 ### v0.11.0
 
   - Improved bake task return values.
 
+### v0.10.0
+
+  - Better handling of versions.
+
+### v0.9.0
+
+  - Add `after_gem_release_version_increment` hook.
+
 ## See Also
 
   - [Bake](https://github.com/ioquatix/bake) — The bake task execution tool.

data/releases.md

@@ -1,5 +1,23 @@
 # Releases
 
+## v0.12.0
+
+  - Add `guard_last_commit_not_version_bump` method to prevent consecutive version bumps.
+  - Add `build_gem_in_worktree` method for building gems in isolated git worktrees.
+  - Improve shell command execution with better error handling and specific exit code access.
+
+## v0.11.1
+
+  - Better integration with `bake`'s default output.
+
 ## v0.11.0
 
   - Improved bake task return values.
+
+## v0.10.0
+
+  - Better handling of versions.
+
+## v0.9.0
+
+  - Add `after_gem_release_version_increment` hook.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bake-gem
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.12.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -56,9 +56,13 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- agent.md
 - bake/gem.rb
+- bake/gem/release.rb
 - bake/gem/release/branch.rb
 - bake/gem/release/version.rb
+- context/getting-started.md
+- context/index.yaml
 - lib/bake/gem.rb
 - lib/bake/gem/helper.rb
 - lib/bake/gem/shell.rb