gempilot 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2af205d18b1882cd54aef57cc2196eecd566dc4e960d8aa03935859dadb94845
+  data.tar.gz: c412a708efa730b78865b98b70cda6a8b968430b31015edc93034acba7cb0dc6
+SHA512:
+  metadata.gz: a58637783d6a69c9dc5cb2c85220612959a47a234fd8e392ed4006311c9ce1b31d4534339a6c55df05066c91eba56bd013ef600f988e2865481b8ac1e82c6d35
+  data.tar.gz: adc65d18871b31d1853b4f1c705dcb5d2efd24ecbab16d6d5010131c5d32ad7158e05ea356e4fa4ab7166a0a47b7484f64be711954465a87efe84727d03cadb0

data/.claude/skills/using-command-kit/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: using-command-kit
+description: Use when building Ruby CLI applications with command_kit or command_mapper gems, structuring subcommands, adding options/arguments, generating files from ERB templates, or prompting users for input in Ruby
+---
+
+# Building Ruby CLIs with CommandKit + CommandMapper
+
+CommandKit is a modular Ruby toolkit for building CLI commands with composable include-based modules. CommandMapper wraps external CLI tools with typed Ruby DSLs. Reference implementation: [Ronin](https://github.com/ronin-rb/ronin).
+
+**Core principle:** Include only what you need. Never hand-roll what CommandKit already provides.
+
+## Quick Reference
+
+| Need | Module | Key Method |
+|------|--------|------------|
+| Subcommand dispatch | `Commands` | `command(name, klass)` |
+| Auto-discover commands | `Commands::AutoLoad` | `AutoLoad.new(dir:, namespace:)` |
+| Options | `Options` | `option :name, value: {type:}, desc:` |
+| Arguments | `Arguments` | `argument :name, required:, desc:` |
+| Prompt user | `Interactive` | `ask`, `ask_yes_or_no`, `ask_multiple_choice` |
+| Colored output | `Colors` | `colors.green("text")` |
+| ERB templates | `FileUtils` | `erb(source, dest)` |
+| String inflection | `Inflector` | `camelize`, `underscore`, `demodularize` |
+| Version flag | `Options::Version` | `version "1.0.0"` |
+| Bug reports | `BugReport` | `bug_report_url "https://..."` |
+| Tables | `Printing::Tables` | `print_table(rows, header:, border:)` |
+| Pager | `Pager` | `pager { |io| io.puts data }` |
+
+All modules prefixed `CommandKit::`.
+
+## CLI Structure
+
+```
+exe/mytool                         # Thin entry (see BUNDLE_GEMFILE note below)
+lib/mytool/cli.rb                  # Commands + AutoLoad
+lib/mytool/cli/command.rb          # Base command (Colors, Interactive, BugReport)
+lib/mytool/cli/commands/foo.rb     # Auto-discovered as "mytool foo"
+data/templates/                    # ERB templates for generators
+```
+
+**exe entry point must set `BUNDLE_GEMFILE`** so it works from any directory:
+```ruby
+#!/usr/bin/env ruby
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+require "bundler/setup"
+require "mytool/cli"
+MyTool::CLI.start
+```
+
+Without this, `require "bundler/setup"` fails with `Bundler::GemfileNotFound` when called from outside the project directory.
+
+See `cli-example.rb` for complete CLI + base command + subcommand implementation.
+
+## Generator Pattern
+
+For file generation commands, build a Generator mixin with `template_dir`, `mkdir`, `erb`, `cp`, `sh` wrappers that print colored actions. See `generator-pattern.rb` for full implementation following Ronin's pattern.
+
+Templates use instance variables set in `run()` via ERB binding:
+```erb
+module <%= @module_name %>
+  VERSION = "0.1.0"
+end
+```
+
+## Boolean Options with Negation
+
+CommandKit does NOT auto-generate `--no-<name>` flags. Use OptionParser's `--[no-]` syntax via `long:`:
+
+```ruby
+# ❌ Only creates --verbose (no way to explicitly disable)
+option :verbose, desc: "Enable verbose output"
+
+# ✅ Creates both --verbose and --no-verbose
+option :verbose, long: '--[no-]verbose', desc: "Enable verbose output"
+```
+
+With `--[no-]`, OptionParser passes `true` for `--verbose`, `false` for `--no-verbose`. When neither is passed, the key is absent from `options`. Use `options.has_key?(:verbose)` to detect "not provided" vs explicit choice.
+
+## Interactive Prompting
+
+Include `Interactive` in base Command. Prompt when args are missing:
+```ruby
+def run(name = nil)
+  @name = name || ask("Name:", required: true)
+  @test = options[:test] || ask_multiple_choice("Framework:", %w[minitest rspec])
+  @git = options.fetch(:git) { ask_yes_or_no("Init git?", default: true) }
+end
+```
+
+**`ask_multiple_choice` return values:**
+- Array form: `ask_multiple_choice("Pick:", %w[minitest rspec])` → returns `String` (`"minitest"`)
+- Hash form: `ask_multiple_choice("Pick:", {"minitest" => :minitest, "rspec" => :rspec})` → returns the **value** (`:minitest`), not the key
+
+Use the Hash form when you need symbols or mapped values.
+
+**Rich prompts** — print colored explanation before `ask()`:
+```ruby
+puts colors.bright_black("A short (one line) summary of what your gem does.")
+ask(colors.green("Summary"), default: "A new Ruby gem")
+```
+
+Also: `ask_secret(prompt)`, `ask_multiline(prompt, terminator:)`.
+
+## CommandMapper
+
+Use `command_mapper` gem for typed interfaces to external CLI tools (bundler, git, etc.). Define subcommands, options with types, and arguments. Execute with `run_command`, `capture_command`, or inspect with `command_string`.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Hand-rolling inflection | `Inflector.camelize(name)` |
+| No `examples` on commands | Always define `examples [...]` |
+| Not prompting for missing args | Include `Interactive`, prompt in `run` |
+| Multiple shell execution paths | Pick one: `system()`, `Open3`, or CommandMapper |
+| Forgetting `bug_report_url` | One line in base Command, inherited everywhere |
+| Skipping `description` | Always set - drives help and command summary |
+| Expecting `--no-flag` to work | Must use `long: '--[no-]flag'` explicitly |
+| Bare `require "bundler/setup"` in exe | Set `ENV["BUNDLE_GEMFILE"]` first |

data/.claude/skills/using-command-kit/cli-example.rb

@@ -0,0 +1,84 @@
+# Complete CommandKit CLI example following Ronin patterns
+#
+# Entry point (exe/mytool):
+#   #!/usr/bin/env ruby
+#   ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+#   require "bundler/setup"
+#   require "mytool/cli"
+#   MyTool::CLI.start
+
+# lib/mytool/cli.rb
+require "command_kit/commands"
+require "command_kit/commands/auto_load"
+require "command_kit/options/version"
+
+module MyTool
+  class CLI
+    include CommandKit::Commands
+    include CommandKit::Commands::AutoLoad.new(
+      dir:       "#{__dir__}/cli/commands",
+      namespace: "#{self}::Commands"
+    )
+    include CommandKit::Options::Version
+
+    command_name "mytool"
+    version MyTool::VERSION
+
+    command_aliases["g"] = "generate"
+  end
+end
+
+# lib/mytool/cli/command.rb
+module MyTool
+  class CLI
+    class Command < CommandKit::Command
+      include CommandKit::Colors
+      include CommandKit::Interactive
+
+      bug_report_url "https://github.com/user/mytool/issues/new"
+    end
+  end
+end
+
+# lib/mytool/cli/commands/generate.rb
+module MyTool
+  class CLI
+    module Commands
+      class Generate < Command
+        include Generator
+
+        template_dir File.join(ROOT, "data", "templates", "component")
+
+        usage "[options] NAME"
+        description "Generate a new component"
+
+        examples [
+          "my_widget",
+          "--test rspec my_widget",
+          "--no-git my_widget"
+        ]
+
+        option :test, value: {
+          type: { "minitest" => :minitest, "rspec" => :rspec },
+          default: :minitest
+        }, desc: "Test framework"
+
+        option :git, desc: "Initialize git repo"
+
+        argument :name, required: true, desc: "Component name"
+
+        # Prompt for missing args via CommandKit::Interactive
+        def run(name = nil)
+          @name = name || ask("Component name:", required: true)
+          @module_name = CommandKit::Inflector.camelize(@name)
+          @test = options[:test] || ask_multiple_choice("Test framework:", %w[minitest rspec])
+          @git = options.fetch(:git) { ask_yes_or_no("Initialize git?", default: true) }
+
+          mkdir @name
+          erb "main.rb.erb", "#{@name}/lib/#{@name}.rb"
+          erb "version.rb.erb", "#{@name}/lib/#{@name}/version.rb"
+        end
+      end
+    end
+  end
+end

data/.claude/skills/using-command-kit/generator-pattern.rb

@@ -0,0 +1,62 @@
+# Generator mixin following ronin-core's Core::CLI::Generator pattern.
+# Provides template_dir, mkdir, erb, cp, sh wrappers with colored output.
+# See: ronin-core/lib/ronin/core/cli/generator.rb
+
+module MyTool
+  class CLI
+    module Generator
+      include CommandKit::Colors
+      include CommandKit::FileUtils
+
+      def self.included(command)
+        command.extend ClassMethods
+      end
+
+      module ClassMethods
+        def template_dir(path = nil)
+          if path
+            @template_dir = File.expand_path(path)
+          else
+            @template_dir || (superclass.template_dir if superclass.respond_to?(:template_dir))
+          end
+        end
+      end
+
+      attr_reader :template_dir
+
+      def initialize(**kwargs)
+        super
+        unless (@template_dir = self.class.template_dir)
+          raise NotImplementedError, "#{self.class} did not define template_dir"
+        end
+      end
+
+      def print_action(action, source = nil, dest)
+        line = "\t#{colors.bold(colors.green(action))}"
+        line << "\t#{colors.green(source)}" if source
+        line << "\t#{colors.green(dest)}" if dest
+        puts line
+      end
+
+      def mkdir(path)
+        print_action "mkdir", path
+        ::FileUtils.mkdir_p(path)
+      end
+
+      def cp(source, dest)
+        print_action "cp", source, dest
+        ::FileUtils.cp(File.join(@template_dir, source), dest)
+      end
+
+      def erb(source, dest = nil)
+        print_action("erb", source, dest) if dest
+        super(File.join(@template_dir, source), dest)
+      end
+
+      def sh(command, *arguments)
+        print_action "run", [command, *arguments].join(" ")
+        system(command, *arguments)
+      end
+    end
+  end
+end

data/.rspec

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

data/.rubocop.yml

@@ -0,0 +1,281 @@
+# ===========================================================================
+# 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
+  - rubocop-minitest
+  - rubocop-performance
+  - rubocop-rake
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.4
+  Exclude:
+    - bin/*
+    - vendor/**/*
+    - data/templates/**/*
+    - references/**/*
+
+# ===========================================================================
+# 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
+# ===========================================================================
+
+# Zeitwerk loaders are mutable by design — only flag literal mutable values.
+Style/MutableConstant:
+  EnforcedStyle: literals
+
+# Short blocks push toward small chained steps instead of fat lambdas.
+Metrics/BlockLength:
+  Max: 8
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+    - method_call
+  AllowedMethods:
+    - command
+  Exclude:
+    - "test/**/*"
+    - "gempilot.gemspec"
+    - "rakelib/**/*.rake"
+
+Metrics/ClassLength:
+  Exclude:
+    - "test/**/*"
+
+Metrics/MethodLength:
+  Exclude:
+    - "test/**/*"
+
+Metrics/AbcSize:
+  Exclude:
+    - "test/**/*"
+
+Claude/NoFancyUnicode:
+  Exclude:
+    - "gempilot.gemspec"
+
+# Minitest tests legitimately define many assertions per test method
+# when testing multi-file generators. Default is 3, too tight.
+Minitest/MultipleAssertions:
+  Max: 10
+
+# Anonymous forwarding (*, **, &) breaks TruffleRuby, JRuby, and
+# Ruby < 3.2. Named args are explicit and portable.
+#
+#   # bad — anonymous forwarding, not portable
+#   def process(*, **, &)
+#     other_method(*, **, &)
+#   end
+#
+#   # good — named, works everywhere, readable
+#   def process(*args, **kwargs, &block)
+#     other_method(*args, **kwargs, &block)
+#   end
+Style/ArgumentsForwarding:
+  Enabled: false
+
+# Explicit begin/rescue/end is clearer than implicit method-body rescue.
+# The begin block scopes what's being rescued. Without it, the rescue
+# looks like it belongs to the method signature.
+#
+#   # bad — what exactly is being rescued here?
+#   def process
+#     logger.info("starting")
+#     result = dangerous_call
+#     logger.info("done")
+#   rescue NetworkError => e
+#     retry_later(e)
+#   end
+#
+#   # good — begin scopes the danger
+#   def process
+#     logger.info("starting")
+#     begin
+#       result = dangerous_call
+#     rescue NetworkError => e
+#       retry_later(e)
+#     end
+#     logger.info("done")
+#   end
+Style/RedundantBegin:
+  Enabled: false
+
+# Classes get rdoc. Run `rake rdoc` and keep it honest.
+#
+#   # bad
+#   class UserService
+#     def call(user) = process(user)
+#   end
+#
+#   # good
+#   # Handles user lifecycle operations including activation,
+#   # deactivation, and profile updates.
+#   class UserService
+#     def call(user) = process(user)
+#   end
+Style/Documentation:
+  Enabled: true
+  Exclude:
+    - "spec/**/*"
+    - "test/**/*"
+
+# Trailing commas in multiline literals and arguments.
+# Cleaner diffs — adding an element doesn't touch the previous line.
+# Also saves keystrokes when appending.
+#
+#   # bad
+#   method_call(
+#     arg1,
+#     arg2
+#   )
+#
+#   # good
+#   method_call(
+#     arg1,
+#     arg2,
+#   )
+#
+#   # bad
+#   hash = {
+#     name: "Alice",
+#     age: 30
+#   }
+#
+#   # good
+#   hash = {
+#     name: "Alice",
+#     age: 30,
+#   }
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: comma
+
+# ===========================================================================
+# RSpec — rubocop-rspec overrides
+# ===========================================================================
+
+# Not every describe block wraps a class. Feature specs, request specs,
+# and integration tests describe behavior, not objects.
+#
+#   # "bad" according to this cop — but perfectly valid
+#   RSpec.describe "User registration flow" do
+#     it "sends a welcome email" do
+#       ...
+#     end
+#   end
+#
+#   # this cop only wants
+#   RSpec.describe User do
+#     ...
+#   end
+RSpec/DescribeClass:
+  Enabled: false
+
+# Subject placement is a readability call, not a rule. Sometimes
+# let blocks need to come first to make subject comprehensible.
+#
+#   # "bad" according to this cop
+#   let(:user) { create(:user) }
+#   subject { described_class.new(user) }
+#
+#   # cop wants subject first — but then you're reading
+#   # `described_class.new(user)` before knowing what `user` is
+RSpec/LeadingSubject:
+  Enabled: false
+
+# Block style for expect { }.to change { } reads like a sentence
+# and makes the mutation scope explicit.
+#
+#   # bad (method style)
+#   expect { user.activate! }.to change(user, :active?).from(false).to(true)
+#
+#   # good (block style)
+#   expect { user.activate! }.to change { user.active? }.from(false).to(true)
+RSpec/ExpectChange:
+  EnforcedStyle: block
+
+RSpec/NamedSubject:
+  Enabled: false
+
+# have_file_content matcher accepts a filename string in expect()
+RSpec/ExpectActual:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.4.8

data/CLAUDE.md

@@ -0,0 +1,45 @@
+## Gempilot
+
+A CLI tool for creating and managing Ruby gems, built on CommandKit.
+
+### Terminology
+- **"the repo"** — this gempilot codebase
+- **"gem repos"** — gems generated by gempilot (output of `gempilot create`)
+
+### Commands
+- `gempilot create` — Scaffold a new gem (templates in `data/templates/gem/`)
+- `gempilot new` — Generate a class, module, or command in an existing gem (templates in `data/templates/new/`)
+- `gempilot destroy` — Remove a class, module, or command from an existing gem
+- `gempilot bump` — Bump version in `version.rb` (patch default, or minor/major)
+- `gempilot release` — Thin proxy to `rake release`
+- `gempilot console` — Thin proxy to `bin/console`
+
+### Architecture
+- Uses Zeitwerk for autoloading
+- Uses CommandKit for CLI framework (commands, options, arguments, interactive prompts)
+- Uses CommandKit::Inflector for name inflection
+- Generator module (`lib/gempilot/cli/generator.rb`) provides template rendering via ERB
+- GemContext module (`lib/gempilot/cli/gem_context.rb`) shared by new, destroy, release, console
+- CommandKit::Commands::AutoLoad maps filenames in `commands/` to command names
+
+### Testing
+- Minitest with minitest-reporters
+- Run tests: `bundle exec rake test`
+
+### Generated Gem Features
+- Zeitwerk autoloading with `LOADER` constant exposed for eager loading
+- Zeitwerk validation test (`test/zeitwerk_test.rb` or `spec/zeitwerk_spec.rb`)
+- `rake zeitwerk:validate` task to verify naming conventions
+- Choice of minitest or rspec
+- RuboCop with framework-specific plugins
+- GitHub Actions CI workflow (`.github/workflows/ci.yml`)
+- `git ls-files`-based gemspec with glob fallback for non-git repos
+- Version management rake tasks in `rakelib/version.rake` (current, bump, commit, revert, release:full)
+
+### Notes
+- AutoLoad uses block form in `cli.rb` with explicit `summary:` per command (lazy loading means descriptions aren't available at help time without this)
+
+
+## ISSUES
+
+1. RESOLVED — `exe/gempilot` had unconditional `ENV["BUNDLE_GEMFILE"]` and `require "bundler/setup"`, causing `Gemfile not found` after `gem install`. Removed both lines; RubyGems handles load paths for installed gems. (Ronin avoids this with a conditional `Gemfile.lock` check, but gempilot's `exe/`+`bin/` separation makes that unnecessary.)

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 David Gillis
+
+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.