gempilot 0.2.0

data/README.md

@@ -0,0 +1,140 @@
+# Gempilot
+
+A CLI toolkit for creating and managing Ruby gems with modern conventions.
+
+Gempilot scaffolds production-ready gems with Zeitwerk autoloading, RuboCop,
+GitHub Actions CI, and integrated version management. It also generates
+classes, modules, and commands within existing gems.
+
+## Installation
+
+```bash
+gem install gempilot
+```
+
+Requires Ruby >= 3.4.
+
+## Quick Start
+
+```bash
+gempilot create my_gem
+cd my_gem
+bundle exec rake
+```
+
+This creates a fully configured gem with tests, linting, CI, and version
+management — ready to develop.
+
+## Commands
+
+### `gempilot create`
+
+Scaffold a new gem.
+
+```bash
+gempilot create my_gem
+gempilot create --test rspec --exe my_gem
+gempilot create --test minitest --no-git my_gem
+```
+
+Options:
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--test {minitest\|rspec}` | Test framework | prompted |
+| `--[no-]exe` | Create executable in `exe/` | prompted |
+| `--[no-]git` | Initialize git repo | prompted |
+| `--branch NAME` | Git branch name | `master` |
+| `--summary TEXT` | One-line gem description | prompted |
+| `--author NAME` | Author name | `git config user.name` |
+| `--email EMAIL` | Author email | `git config user.email` |
+| `--ruby-version VER` | Minimum Ruby version | current Ruby |
+
+All options are prompted interactively if omitted.
+
+### `gempilot new`
+
+Generate a class, module, or command in an existing gem. Run from the gem root.
+
+```bash
+gempilot new class MyGem::Services::Authentication
+gempilot new module MyGem::Middleware
+gempilot new command deploy
+```
+
+Creates the source file under `lib/` and a corresponding test file. For
+commands, generates a CommandKit command class in `lib/<gem>/cli/commands/`.
+
+### `gempilot destroy`
+
+Remove a class, module, or command. Cleans up empty parent directories.
+
+```bash
+gempilot destroy class MyGem::Services::Authentication
+gempilot destroy command deploy
+```
+
+### `gempilot bump`
+
+Bump the version in `lib/<gem>/version.rb`.
+
+```bash
+gempilot bump          # patch (default)
+gempilot bump minor
+gempilot bump major
+```
+
+### `gempilot release`
+
+Delegates to `rake release` to build and push the gem.
+
+### `gempilot console`
+
+Delegates to `bin/console` for an interactive IRB session with the gem loaded.
+
+## Generated Gem Features
+
+Every gem scaffolded by `gempilot create` includes:
+
+- **Zeitwerk autoloading** with `LOADER` constant and `rake zeitwerk:validate`
+- **Test framework** — Minitest or RSpec, with a Zeitwerk eager-load test
+- **RuboCop** with `rubocop-claude`, `rubocop-performance`, `rubocop-rake`, and
+  framework-specific plugins (`rubocop-minitest` or `rubocop-rspec`)
+- **GitHub Actions CI** running tests and RuboCop
+- **Version management** rake tasks (see below)
+- **`bin/console`** and **`bin/setup`** scripts
+- **Gemspec** with `git ls-files` and glob fallback, MFA required for RubyGems
+
+### Version Management Tasks
+
+Generated gems include rake tasks for the full version lifecycle:
+
+| Task | Description |
+|------|-------------|
+| `rake version:current` | Display the current version |
+| `rake version:bump` | Increment the patch version |
+| `rake version:commit` | Commit the version file change |
+| `rake version:tag` | Create a git tag for the version |
+| `rake version:untag` | Delete the version git tag |
+| `rake version:reset` | Reset the last version bump commit |
+| `rake version:revert` | Revert the last version bump commit |
+| `rake version:release` | Bump, commit, and tag (combined) |
+| `rake version:unrelease` | Untag and reset (combined) |
+| `rake version:github:release` | Push and create a GitHub release |
+| `rake version:github:unrelease` | Delete the GitHub release |
+| `rake version:github:list` | List GitHub releases |
+
+## Development
+
+```bash
+git clone https://github.com/gillisd/gempilot.git
+cd gempilot
+bundle install
+bundle exec rake
+```
+
+`rake` runs the Minitest suite, RSpec suite, and RuboCop.
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,44 @@
+require "bundler/gem_tasks"
+Bundler::GemHelper.install_tasks name: "gempilot"
+
+require "minitest/test_task"
+Minitest::TestTask.create
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+
+require_relative 'lib/gempilot'
+
+namespace :spec do
+  desc "Prints the specification suite in documentation format and exits"
+  task :print do
+    exec("rspec", "--format", "documentation", "--dry-run")
+  end
+end
+
+namespace :zeitwerk do
+  desc "Verify all files follow Zeitwerk naming conventions"
+  task :validate do
+    ruby "-e", <<~RUBY
+      require 'gempilot'
+      Gempilot::LOADER.eager_load(force: true)
+      puts 'Zeitwerk: All files loaded successfully.'
+    RUBY
+  end
+end
+
+require "rubocop/rake_task"
+RuboCop::RakeTask.new do |t|
+  t.patterns = [
+    'lib/*.rb',
+    'lib/**/*.rb',
+    'spec/*.rb',
+    'spec/**/*.rb',
+    'test/*.rb',
+    'test/**/*.rb',
+  ]
+end
+
+Gempilot::VersionTask.new
+
+task default: [:test, :spec, :rubocop]

data/data/templates/gem/Gemfile.erb

@@ -0,0 +1,23 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem "gempilot", require: false
+<% if @test_framework == :minitest -%>
+gem "minitest"
+gem "minitest-reporters"
+<% end -%>
+gem "rake"
+<% if @test_framework == :rspec -%>
+gem "rspec", "~> 3.0"
+<% end -%>
+gem "rubocop"
+gem "rubocop-claude"
+<% if @test_framework == :minitest -%>
+gem "rubocop-minitest"
+<% end -%>
+gem "rubocop-performance"
+gem "rubocop-rake"
+<% if @test_framework == :rspec -%>
+gem "rubocop-rspec"
+<% end -%>

data/data/templates/gem/LICENSE.txt.erb

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) <%= Time.now.year %> <%= @author %>
+
+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/data/templates/gem/README.md.erb

@@ -0,0 +1,25 @@
+# <%= @module_name %>
+
+<%= @summary %>
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add <%= @gem_name %>
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install <%= @gem_name %>
+
+## Usage
+
+TODO: Write usage instructions here.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/data/templates/gem/Rakefile.erb

@@ -0,0 +1,36 @@
+require "bundler/gem_tasks"
+
+<% if @test_framework == :minitest -%>
+require "minitest/test_task"
+<% elsif @test_framework == :rspec -%>
+require "rspec/core/rake_task"
+<% end -%>
+
+<% if @test_framework == :minitest -%>
+Minitest::TestTask.create
+<% elsif @test_framework == :rspec -%>
+RSpec::Core::RakeTask.new(:spec)
+<% end -%>
+
+require "rubocop/rake_task"
+RuboCop::RakeTask.new
+
+require "gempilot/version_task"
+Gempilot::VersionTask.new
+
+namespace :zeitwerk do
+  desc "Verify all files follow Zeitwerk naming conventions"
+  task :validate do
+    ruby "-e", <<~RUBY
+      require '<%= @require_path %>'
+      <%= @module_name %>::LOADER.eager_load(force: true)
+      puts 'Zeitwerk: All files loaded successfully.'
+    RUBY
+  end
+end
+
+<% if @test_framework == :minitest -%>
+task default: [:test, :rubocop]
+<% elsif @test_framework == :rspec -%>
+task default: [:spec, :rubocop]
+<% end -%>

data/data/templates/gem/bin/console.erb

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "<%= @require_path %>"
+require "irb"
+
+IRB.start(__FILE__)

data/data/templates/gem/bin/setup.erb

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install

data/data/templates/gem/dotfiles/github/workflows/ci.yml.erb

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['<%= @ruby_version %>']
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true
+<% if @test_framework == :minitest -%>
+    - name: Run tests
+      run: bundle exec rake test
+<% elsif @test_framework == :rspec -%>
+    - name: Run specs
+      run: bundle exec rake spec
+<% end -%>
+    - name: Run RuboCop
+      run: bundle exec rake rubocop

data/data/templates/gem/dotfiles/gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+Gemfile.lock
+*.gem
+.rspec_status

data/data/templates/gem/dotfiles/rubocop.yml.erb

@@ -0,0 +1,209 @@
+# ===========================================================================
+# RuboCop Configuration
+#
+# Base: Stock RuboCop defaults
+# AI guardrails: rubocop-claude plugin (all Claude/ cops + stricter metrics)
+# Performance: rubocop-performance (with chain-hostile cops disabled)
+#
+# Philosophy: idiomatic Ruby, pipeline-style chaining, strict for AI agents,
+# readable for humans.
+# ===========================================================================
+
+plugins:
+  - rubocop-claude
+<% if @test_framework == :minitest -%>
+  - rubocop-minitest
+<% elsif @test_framework == :rspec -%>
+  - rubocop-rspec
+<% end -%>
+  - rubocop-performance
+  - rubocop-rake
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: <%= minor_version_for @ruby_version %>
+  Exclude:
+    - bin/*
+    - vendor/**/*
+    - lib/core_ext/**/*
+    - rakelib/project.rb
+    - rakelib/project_version.rb
+    - rakelib/version_tag.rb
+    - rakelib/github_release.rb
+    - rakelib/strict_shell.rb
+<% if @hyphenated -%>
+    - lib/<%= @gem_name %>.rb
+<% end -%>
+
+# ===========================================================================
+# Overrides from stock — personal style preferences
+# ===========================================================================
+
+# Double quotes everywhere. One less decision to make.
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+# Frozen string literal is transitional cruft. Ruby 3.4 has chilled strings,
+# full default freeze is coming in a future Ruby.
+Style/FrozenStringLiteralComment:
+  EnforcedStyle: never
+
+# Pipeline style. Chaining multi-line blocks is the whole point.
+Style/MultilineBlockChain:
+  Enabled: false
+
+# Block delimiters are a taste call. Pipeline code uses braces for chaining,
+# do/end for side effects. No cop captures this nuance.
+Style/BlockDelimiters:
+  Enabled: false
+
+# Write arrays like arrays.
+Style/WordArray:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: false
+
+# Argument indentation: consistent 2-space indent, not aligned to first arg.
+Layout/FirstArgumentIndentation:
+  EnforcedStyle: consistent
+
+# Dot-aligned chaining. Dots form a visual column.
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: aligned
+
+# ===========================================================================
+# Overrides from rubocop-claude — loosen where pipeline style conflicts
+# ===========================================================================
+
+Claude/NoOverlyDefensiveCode:
+  MaxSafeNavigationChain: 2
+
+Style/SafeNavigation:
+  MaxChainLength: 2
+
+# Allow `return a, b` for tuple-style returns.
+Style/RedundantReturn:
+  AllowMultipleReturnValues: true
+
+# ===========================================================================
+# Overrides from rubocop-performance — disable chain-hostile cops
+# ===========================================================================
+
+Performance/ChainArrayAllocation:
+  Enabled: false
+
+Performance/MapMethodChain:
+  Enabled: false
+
+# ===========================================================================
+# Additional tightening — not set by stock or rubocop-claude
+# ===========================================================================
+
+# Short blocks push toward small chained steps instead of fat lambdas.
+Metrics/BlockLength:
+  Max: 8
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+    - method_call
+  AllowedMethods:
+    - command
+<% if @test_framework == :minitest -%>
+    - test
+<% elsif @test_framework == :rspec -%>
+    - describe
+    - context
+    - shared_examples
+    - shared_examples_for
+    - shared_context
+<% end -%>
+  Exclude:
+    - "<%= @gem_name %>.gemspec"
+    - "rakelib/**/*"
+
+# Gemspec and rake files use patterns that trigger Claude cops legitimately.
+Claude/NoFancyUnicode:
+  Exclude:
+    - "<%= @gem_name %>.gemspec"
+
+Claude/MysteryRegex:
+  Exclude:
+    - "rakelib/**/*"
+
+# Zeitwerk loaders are mutable by design — only flag literal mutable values.
+Style/MutableConstant:
+  EnforcedStyle: literals
+
+<% if @test_framework == :minitest -%>
+# Minitest tests can legitimately need many assertions per method
+# when verifying multi-step operations.
+Minitest/MultipleAssertions:
+  Max: 10
+<% elsif @test_framework == :rspec -%>
+# Shared test contexts legitimately define many helpers.
+RSpec/MultipleMemoizedHelpers:
+  Max: 10
+<% end -%>
+
+# Anonymous forwarding (*, **, &) breaks TruffleRuby, JRuby, and
+# Ruby < 3.2. Named args are explicit and portable.
+Style/ArgumentsForwarding:
+  Enabled: false
+
+# Explicit begin/rescue/end is clearer than implicit method-body rescue.
+Style/RedundantBegin:
+  Enabled: false
+
+# Compact class names are fine for small files and tests.
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+# Classes get rdoc.
+Style/Documentation:
+  Enabled: true
+  Exclude:
+<% if @test_framework == :minitest -%>
+    - "test/**/*"
+<% elsif @test_framework == :rspec -%>
+    - "spec/**/*"
+<% end -%>
+
+# Trailing commas in multiline literals and arguments.
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: comma
+
+<% if @test_framework == :rspec -%>
+# ===========================================================================
+# RSpec — rubocop-rspec overrides
+# ===========================================================================
+
+# Not every describe block wraps a class.
+RSpec/DescribeClass:
+  Enabled: false
+
+# Subject placement is a readability call, not a rule.
+RSpec/LeadingSubject:
+  Enabled: false
+
+# Block style for expect { }.to change { } reads like a sentence.
+RSpec/ExpectChange:
+  EnforcedStyle: block
+
+RSpec/NamedSubject:
+  Enabled: false
+
+# have_file_content matcher accepts a filename string in expect()
+RSpec/ExpectActual:
+  Enabled: false
+<% end -%>

data/data/templates/gem/dotfiles/ruby-version.erb

@@ -0,0 +1 @@
+<%= @ruby_version %>

data/data/templates/gem/exe/gem_name.erb

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+
+require "<%= @require_path %>"

data/data/templates/gem/gemspec.erb

@@ -0,0 +1,27 @@
+require_relative "lib/<%= @require_path %>/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "<%= @gem_name %>"
+  spec.version = <%= @module_name %>::VERSION
+  spec.authors = ["<%= @author %>"]
+  spec.email = ["<%= @email %>"]
+  spec.summary = "<%= @summary %>"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= <%= @ruby_version %>"
+
+  gemspec_file = File.basename(__FILE__)
+  files = IO.popen(["git", "ls-files", "-z"], chdir: __dir__, err: IO::NULL) { |ls|
+    ls.readlines("\x0", chomp: true).reject do |f|
+      (f == gemspec_file) ||
+        f.start_with?("bin/", "test/", "spec/", "features/", ".git", "Gemfile")
+    end
+  }
+  files = Dir.glob("{lib,exe}/**/*").push("README.md", "LICENSE.txt", "Rakefile") if files.empty?
+  spec.files = files
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "zeitwerk"
+  spec.metadata["rubygems_mfa_required"] = "true"
+end

data/data/templates/gem/lib/gem_name/version.rb.erb

@@ -0,0 +1,7 @@
+<% @module_parts.each_with_index do |part, i| -%>
+<%= "  " * i %>module <%= part %>
+<% end -%>
+<%= "  " * @module_parts.size %>VERSION = "0.0.1".freeze
+<% @module_parts.size.times do |i| -%>
+<%= "  " * (@module_parts.size - 1 - i) %>end
+<% end -%>

data/data/templates/gem/lib/gem_name.rb.erb

@@ -0,0 +1,16 @@
+<% if @hyphenated -%>
+require "<%= @require_path %>"
+<% else -%>
+require "zeitwerk"
+
+##
+# Top-level namespace for the <%= @gem_name %> gem.
+module <%= @module_name %>
+  LOADER = Zeitwerk::Loader.for_gem
+  LOADER.setup
+
+  ##
+  # Base error class for <%= @gem_name %>.
+  class Error < StandardError; end
+end
+<% end -%>

data/data/templates/gem/lib/gem_name_extension.rb.erb

@@ -0,0 +1,20 @@
+require "zeitwerk"
+
+<% @module_parts.each_with_index do |part, i| -%>
+<%= "  " * i %>##
+<% if i == 0 -%>
+<%= "  " * i %># Top-level namespace for the <%= @gem_name %> gem.
+<% else -%>
+<%= "  " * i %># Extension namespace for <%= @module_parts[0..i].join("::") %>.
+<% end -%>
+<%= "  " * i %>module <%= part %>
+<% end -%>
+<%= "  " * @module_parts.size %>LOADER = Zeitwerk::Loader.for_gem_extension(<%= @base_module %>)
+<%= "  " * @module_parts.size %>LOADER.setup
+
+<%= "  " * @module_parts.size %>##
+<%= "  " * @module_parts.size %># Base error class for <%= @gem_name %>.
+<%= "  " * @module_parts.size %>class Error < StandardError; end
+<% @module_parts.size.times do |i| -%>
+<%= "  " * (@module_parts.size - 1 - i) %>end
+<% end -%>

data/data/templates/gem/rspec.erb

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/data/templates/gem/spec/gem_name_spec.rb.erb

@@ -0,0 +1,5 @@
+RSpec.describe <%= @module_name %> do
+  it "has a version number" do
+    expect(<%= @module_name %>::VERSION).not_to be_nil
+  end
+end

data/data/templates/gem/spec/spec_helper.rb.erb

@@ -0,0 +1,10 @@
+require "<%= @require_path %>"
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = ".rspec_status"
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+end

data/data/templates/gem/spec/zeitwerk_spec.rb.erb

@@ -0,0 +1,5 @@
+RSpec.describe "Zeitwerk" do
+  it "eager loads all files without errors" do
+    expect { <%= @module_name %>::LOADER.eager_load(force: true) }.not_to raise_error
+  end
+end

data/data/templates/gem/test/gem_name_test.rb.erb

@@ -0,0 +1,7 @@
+require "test_helper"
+
+class <%= @module_name %>Test < Minitest::Test
+  def test_that_it_has_a_version_number
+    refute_nil <%= @module_name %>::VERSION
+  end
+end