@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/ruby/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: ruby
+description: "Use when writing or refactoring plain Ruby outside Rails — scripts, CLIs, gems, libraries: Enumerable chains and blocks, module mixins and value objects, Bundler/gemspec packaging, whether metaprogramming earns its keep, Minitest or RSpec, Ruby 3.4/4.0 frozen-string hygiene. NOT Rails, ActiveRecord, or ActiveSupport idioms (that is `rails`)."
+tags: [ruby, gems, bundler, metaprogramming, rspec, minitest, enumerable]
+recommends: [rails, testing-web, secure-coding]
+profiles: []
+origin: ai-hub
+---
+
+# Idiomatic Ruby, the language
+
+Write Ruby a senior Rubyist would sign off on: expression-oriented, block-driven,
+leaning on `Enumerable` and `Comparable` instead of hand-rolled loops, with
+`frozen_string_literal` hygiene and a real `Gemfile`/`.gemspec` when you package.
+
+This is **Ruby the language and its non-Rails ecosystem** — blocks, modules, gems,
+metaprogramming, Minitest/RSpec. Delegate: Rails apps, ActiveRecord models, controllers,
+migrations, views, Hotwire — anything that loads Rails or uses ActiveSupport/ActiveRecord
+idioms — to [`rails`](../rails/SKILL.md); the same task in another language to
+[`python`](../python/SKILL.md), [`go`](../go/SKILL.md), [`rust`](../rust/SKILL.md),
+[`elixir`](../elixir/SKILL.md), [`php`](../php/SKILL.md) or
+[`typescript`](../typescript/SKILL.md); the CI pipeline that runs your Ruby tests to
+[`github-actions`](../github-actions/SKILL.md) — this skill writes the tests, not the workflow.
+
+Targets **Ruby 4.0** (released 2025-12-25) on **3.4** semantics: Prism is the default
+parser, string literals warn on mutation without a magic comment, `it` is an implicit
+block param, and `Set` is now a core class.
+
+## Mental model
+
+Internalize these before writing a line:
+
+1. **Everything is an expression and returns a value.** `if`, `case`, blocks, method
+   bodies all yield a value — name and return it instead of threading a flag.
+2. **Everything is an object receiving messages.** `5.times`, `nil.to_a`, `"x".freeze`.
+   There are no primitives to special-case.
+3. **Reach for `Enumerable` before you write a loop.** A manual index loop in Ruby is
+   almost always a `map`/`select`/`reduce` you have not spotted yet.
+4. **Prefer returning new values to mutating in place.** Mutation is allowed but it is
+   the exception you justify, not the default.
+5. **Freeze your string literals.** New files start with `# frozen_string_literal: true`.
+6. **Dynamism is the trap, not the feature.** Metaprogramming is a scalpel; if a plain
+   method, a `Struct`, or a `Data` does the job, use that.
+
+## Blocks, procs, lambdas, yield
+
+Blocks are the spine of Ruby. A method takes a block implicitly via `yield`, or
+explicitly with `&block` when it must store or forward it.
+
+```ruby
+# frozen_string_literal: true
+
+# Implicit: yield runs the caller's block and returns its value.
+def with_timing
+  start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  result = yield
+  [result, Process.clock_gettime(Process::CLOCK_MONOTONIC) - start]
+end
+
+# Explicit: capture the block as a Proc to forward or store it.
+def retrying(times, &block)
+  attempts = 0
+  begin
+    block.call
+  rescue StandardError
+    (attempts += 1) < times ? retry : raise
+  end
+end
+```
+
+`proc` vs `lambda` differ in two ways that bite:
+
+| Aspect | `proc` / block | `lambda` / `->` |
+|--------|----------------|-----------------|
+| Arity  | Lenient — extra args dropped, missing become `nil` | Strict — wrong count raises `ArgumentError` |
+| `return` | Returns from the enclosing method (can surprise) | Returns from the lambda only |
+
+Rule: use a **lambda** for a function-like value you call yourself; use a **block/proc**
+for the "do this with each element" pattern. For cheap accumulation prefer
+`each_with_object` (returns the seed) or `reduce`; use `tap` (returns the receiver) for
+side effects and `then` for piping a value through a transform.
+
+```ruby
+# Bad: index loop building a result by mutation.
+result = []
+(0...items.length).each { |i| result << items[i].upcase if items[i].size > 3 }
+
+# Good: intent reads top-to-bottom, no index, no pre-seeded array.
+result = items.select { |s| s.size > 3 }.map(&:upcase)
+```
+
+## Enumerable & Comparable
+
+Most loops map to one named method. Pick by **intent**, not by habit:
+
+| You want to…                          | Use                          |
+|---------------------------------------|------------------------------|
+| Transform every element               | `map`                        |
+| Keep / drop by predicate              | `select` / `reject`          |
+| Fold into one value                   | `reduce` / `sum` / `min_by`  |
+| Build a Hash or accumulate into a seed| `each_with_object`           |
+| Count occurrences                     | `tally`                      |
+| Bucket by a key                       | `group_by`                   |
+| First match                           | `find` (`detect`)            |
+| Pair index with element               | `each_with_index`            |
+
+Make your own classes first-class collections by including `Enumerable` and defining
+`each`; get `<`, `>`, `between?`, `clamp`, `sort` for free by including `Comparable` and
+defining `<=>`.
+
+```ruby
+# frozen_string_literal: true
+
+class Playlist
+  include Enumerable
+
+  def initialize(tracks) = @tracks = tracks
+  def each(&) = @tracks.each(&)   # one method unlocks map/select/sort/...
+end
+
+class Version
+  include Comparable
+  attr_reader :major, :minor
+
+  def initialize(major, minor)
+    @major = major
+    @minor = minor
+  end
+
+  def <=>(other) = [major, minor] <=> [other.major, other.minor]
+end
+```
+
+## Modules & composition
+
+Ruby favors composition through mixins over deep inheritance.
+
+- `include M` — adds `M`'s instance methods to instances (the default mixin).
+- `prepend M` — inserts `M` *before* the class in the lookup chain, so `M`'s methods can
+  wrap the originals via `super` (cleaner than aliasing for decoration).
+- `extend M` — adds `M`'s methods as *class/singleton* methods.
+
+Rule: reach for a **module mixin** when the same behavior is shared across unrelated
+classes; reserve inheritance for a genuine is-a hierarchy. Namespace with `module Foo`
+to avoid global constant clashes. Need to patch a class without polluting it globally?
+Use a **refinement** (`refine … using`) — a scoped, reversible scalpel — never a bare
+monkey-patch. Full refinement scoping and `prepend`-wrapping in
+[references/metaprogramming.md](references/metaprogramming.md).
+
+## Value objects: Data vs Struct
+
+```ruby
+# frozen_string_literal: true
+
+Point  = Data.define(:x, :y)         # immutable value object (Ruby 3.2+)
+origin = Point.new(x: 0, y: 0)       # no setters; with(x: 1) returns a copy
+
+Cursor = Struct.new(:x, :y)          # mutable; has setters and is Enumerable
+```
+
+| Need                                       | Reach for     |
+|--------------------------------------------|---------------|
+| Immutable value with equality + `with`     | `Data.define` |
+| Mutable record, or array/positional access | `Struct.new`  |
+
+Default to `Data` for value semantics; pick `Struct` only when you genuinely need
+mutation or positional/`to_a` behavior.
+
+## Metaprogramming, sparingly
+
+Decision rule, in order: **could a plain method, a `Struct`, or a `Data` do this?**
+If yes, do that. Only when the method *names themselves* are dynamic (driven by data or
+config) does metaprogramming earn its keep.
+
+- Prefer `define_method` (defines real, introspectable methods) over `method_missing`
+  (intercepts at call time, slower, invisible to `respond_to?` and tooling).
+- If you *must* use `method_missing`, you **must** also define `respond_to_missing?` —
+  otherwise `respond_to?`, `method`, and duck-typing all lie about your object.
+- Never `eval` a string built from user input.
+
+```ruby
+# Good: dynamic method names, but real methods that introspect and document themselves.
+class Config
+  def initialize(**data) = @data = data
+
+  %i[host port timeout].each do |key|
+    define_method(key)       { @data[key] }
+    define_method("#{key}=") { |value| @data[key] = value }
+  end
+end
+```
+
+Building a real DSL, `instance_eval`/`class_eval`, and the full
+`method_missing` + `respond_to_missing?` pairing live in
+[references/metaprogramming.md](references/metaprogramming.md).
+
+## Gems & Bundler
+
+Bundler is the universal dependency manager. `bundle init` creates a `Gemfile`;
+`bundle install` resolves and writes `Gemfile.lock`; run project binaries with
+`bundle exec` so they use the locked versions.
+
+- Use the **pessimistic constraint** `~> 2.3` (allows `2.x >= 2.3`, blocks `3.0`) for
+  libraries; pin tighter only when forced.
+- **Commit `Gemfile.lock` for applications** (reproducible installs); for a *library*
+  gem, do not commit the lock — let consumers resolve.
+- Scaffold a gem with `bundle gem NAME`, which generates the `lib/`, `test/`/`spec/`,
+  `.gemspec`, and Rakefile layout.
+
+```ruby
+# my_gem.gemspec
+Gem::Specification.new do |spec|
+  spec.name        = "my_gem"
+  spec.version     = MyGem::VERSION       # SemVer: MAJOR.MINOR.PATCH
+  spec.summary     = "One-line description."
+  spec.authors     = ["You"]
+  spec.files       = Dir["lib/**/*.rb"]
+  spec.required_ruby_version = ">= 3.4"
+  spec.add_dependency "thor", "~> 1.3"
+end
+```
+
+Full `bundle gem` tree, publishing flow (`gem build` / `gem push`), and Rake test tasks
+are in [references/gems-and-testing.md](references/gems-and-testing.md).
+
+## Ruby 4.0 / 3.4 hygiene
+
+```ruby
+# frozen_string_literal: true     # without it, 3.4+ warns under -W:deprecated on mutation
+
+nums.map { it * 2 }               # `it` is the implicit single block param (3.4+)
+seen = Set.new([1, 2, 3])         # Set is a core class in 4.0 — no `require "set"`
+```
+
+- The magic comment freezes every string literal in the file; mutating one then raises
+  `FrozenError`. This is the cause of most "my string froze after upgrading" reports.
+- `it` reads cleaner than `_1` for one-arg blocks.
+- Ruby 4.0 ships **ZJIT** (a new JIT written in Rust, successor to YJIT) and removed
+  `Ractor.yield`/`Ractor#take` in favor of `Ractor::Port`.
+
+## Testing
+
+Both ship a clean path; choose by ceremony tolerance:
+
+| Framework | Pick when… |
+|-----------|-----------|
+| **Minitest** | You want the default — ships with Ruby, tiny surface, `assert`-style or spec-style, fast. |
+| **RSpec** | You want the expressive DSL and large ecosystem (`describe`/`context`/`it`/`expect`, `let`, mocks). |
+
+```ruby
+# test/tally_test.rb  (Minitest)
+require "minitest/autorun"
+require "tally"
+
+class TallyTest < Minitest::Test
+  def test_counts_words
+    assert_equal({ "a" => 2, "b" => 1 }, Tally.count("a b a"))
+  end
+end
+```
+
+```ruby
+# spec/tally_spec.rb  (RSpec)
+RSpec.describe Tally do
+  subject(:counts) { described_class.count("a b a") }
+  it { is_expected.to eq("a" => 2, "b" => 1) }
+end
+```
+
+Run via `bundle exec rake test` (Minitest) or `bundle exec rspec` (RSpec). Fuller
+examples with `let`/`subject`/`context` are in
+[references/gems-and-testing.md](references/gems-and-testing.md).
+
+## Linting & typing (optional layers)
+
+- **Linter:** Standard (zero-config, "no bikeshadding" wrapper) when you want one less
+  argument; RuboCop (`.rubocop.yml`, every cop opt-in/out) when the team wants control.
+- **Types:** two coexisting systems — **RBS** (official signatures in separate `.rbs`
+  files, checked by Steep) and **Sorbet** (inline `sig` blocks, with experimental
+  inline-RBS-comment support). Add types only on a library's public surface or a hot,
+  bug-prone core — not on throwaway scripts. RuboCop vs Standard config sits in
+  [references/gems-and-testing.md](references/gems-and-testing.md).
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|--------------|--------------|------------|
+| Monkey-patching a core class globally | Action-at-a-distance; collides with gems and future Ruby | A refinement (scoped) or a wrapper/helper |
+| `method_missing` without `respond_to_missing?` | `respond_to?`/`method`/duck-typing all lie | Pair them, or prefer `define_method` |
+| Mutating a frozen string literal | `FrozenError` after the magic comment | `dup` before mutating, or build a new string |
+| `for x in coll` loops | Leaks the loop var; un-idiomatic | `coll.each`/`map`/`select` |
+| `rescue Exception` (bare) | Swallows `SignalException`, `NoMemoryError`, exit | `rescue StandardError` (or specific classes) |
+| Not committing `Gemfile.lock` for an app | Non-reproducible installs across machines | Commit it for apps; omit only for library gems |
+| `eval` of user-derived input | Remote code execution | Parse explicitly; never `eval` untrusted data |
+| Over-DSLing config a Hash would serve | Hidden control flow, slow `method_missing` | A plain Hash or `Data` object |

package/skills/shared/ruby/evals/README.md

@@ -0,0 +1,12 @@
+# Evals for the `ruby` skill
+
+`cases.yaml` holds three kinds of fixture. `should_trigger` lists prompts whose
+situation this skill should claim (idiomatic plain-Ruby work — Enumerable refactors,
+gem packaging, metaprogramming judgment, Minitest/RSpec, the FrozenError-after-upgrade
+case, plus a Catalan phrasing). `should_not_trigger` lists adjacent prompts that must
+route to a real sibling instead (`rails`, `python`, `elixir`, `github-actions`), each
+with the reason. The single `capability` case is a build-a-gem scenario scored against
+a `must_include` rubric. Run them with the repository's eval harness over `evals/`,
+which matches the trigger/route fixtures against the skill description and checks a
+capability transcript against the rubric. No network or Ruby toolchain is required to
+score the routing cases; the capability rubric is judged on the produced answer.

package/skills/shared/ruby/evals/cases.yaml

@@ -0,0 +1,41 @@
+skill: ruby
+
+should_trigger:
+  - prompt: "Refactor this Ruby loop that builds a hash of counts into something idiomatic"
+    why: "Enumerable refactor (each_with_object/tally) is the core day-to-day use of the skill."
+  - prompt: "I want to package this Ruby code as a gem — what goes in the gemspec and do I commit Gemfile.lock?"
+    why: "Gems + Bundler packaging, including the lock-file commit rule."
+  - prompt: "Should I use method_missing or define_method for this dynamic attribute API?"
+    why: "Metaprogramming judgment call — the skill's signature value-add (prefer define_method, pair method_missing with respond_to_missing?)."
+  - prompt: "Set up tests for my plain Ruby library — Minitest or RSpec, and how do I run them?"
+    why: "Testing-framework decision and rake/rspec wiring for non-Rails Ruby."
+  - prompt: "After upgrading to Ruby 3.4 I suddenly get a FrozenError when mutating a string literal"
+    why: "Non-obvious: the symptom routes to frozen_string_literal hygiene, not a generic bug hunt."
+  - prompt: "Vull escriure una gema en Ruby amb blocs i mòduls, sense Rails"
+    why: "Catalan phrasing for plain-Ruby gem authoring with blocks and modules, explicitly non-Rails."
+  - prompt: "Is a mixin or inheritance better here, and when should I prepend vs include?"
+    why: "Module composition design, a core section of the skill."
+
+should_not_trigger:
+  - prompt: "Add a has_many association and a migration to my User model"
+    route_to: rails
+    why: "ActiveRecord associations and migrations load the Rails framework — that is rails, not plain Ruby."
+  - prompt: "Write this list-comprehension data pipeline in Python with pandas"
+    route_to: python
+    why: "Different language; the Ruby skill does not own Python idioms."
+  - prompt: "Build a GenServer that supervises a pool of workers"
+    route_to: elixir
+    why: "BEAM/OTP concurrency belongs to elixir."
+  - prompt: "Set up GitHub Actions CI to run my Ruby tests on every push"
+    route_to: github-actions
+    why: "Authoring the CI workflow is the pipeline skill; this skill writes the tests, not the YAML workflow."
+
+capability:
+  - scenario: "Write a small non-Rails Ruby gem `tally` that exposes a module method counting word frequencies in a string, with a test."
+    must_include:
+      - "A `# frozen_string_literal: true` magic comment at the top of source files."
+      - "An Enumerable idiom (each_with_object, tally, or group_by) rather than a manual index loop."
+      - "A module (e.g. `module Tally`) holding the public method, not just a top-level def."
+      - "Bundler/gem packaging signal: a .gemspec or Gemfile, with a sane version constraint (~>)."
+      - "A real test in Minitest or RSpec that asserts the counts."
+      - "No gratuitous metaprogramming (no method_missing/eval where a plain method suffices)."

package/skills/shared/ruby/references/gems-and-testing.md

@@ -0,0 +1,208 @@
+# Gems, Bundler, and testing, in depth
+
+## bundle gem layout
+
+`bundle gem tally` scaffolds a conventional gem:
+
+```text
+tally/
+├── tally.gemspec
+├── Gemfile                 # usually just: gemspec
+├── Rakefile
+├── lib/
+│   ├── tally.rb            # requires lib/tally/version.rb, defines the module
+│   └── tally/
+│       └── version.rb      # Tally::VERSION = "0.1.0"
+├── sig/
+│   └── tally.rbs           # optional RBS signatures
+└── test/  (or spec/)
+    ├── test_helper.rb
+    └── tally_test.rb
+```
+
+`lib/tally.rb` is the entry point loaded by `require "tally"`. Keep the public API in
+the top-level module; put implementation in `lib/tally/`.
+
+## The .gemspec
+
+```ruby
+# frozen_string_literal: true
+
+require_relative "lib/tally/version"
+
+Gem::Specification.new do |spec|
+  spec.name        = "tally"
+  spec.version     = Tally::VERSION
+  spec.summary     = "Count word frequencies."
+  spec.description = "A tiny, dependency-free word-frequency counter."
+  spec.authors     = ["You"]
+  spec.license     = "MIT"
+  spec.homepage    = "https://github.com/you/tally"
+
+  spec.required_ruby_version = ">= 3.4"
+  spec.files     = Dir["lib/**/*.rb", "README.md", "LICENSE.txt"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "thor", "~> 1.3"          # runtime dep, pessimistic constraint
+  spec.metadata["rubygems_mfa_required"] = "true"
+end
+```
+
+Declare development tools (rake, minitest, rubocop) in the `Gemfile`'s `:development`
+group or via `spec.add_development_dependency`, not as runtime deps.
+
+## SemVer and version constraints
+
+Versions are `MAJOR.MINOR.PATCH`. Bump MAJOR on a breaking change, MINOR on a
+backward-compatible feature, PATCH on a fix.
+
+| Constraint | Allows | Use for |
+|------------|--------|---------|
+| `~> 1.3`   | `>= 1.3.0, < 2.0` | Library deps — accept features and fixes, block breaks |
+| `~> 1.3.2` | `>= 1.3.2, < 1.4.0` | Pin to a patch line when a minor broke you |
+| `>= 1.3`   | any future major | Rarely; you are promising forward compat |
+| `= 1.3.2`  | exactly that | Last resort; you own the upgrade churn |
+
+`Gemfile.lock`: commit it for **applications** (reproducible installs everywhere); do
+**not** commit it for a published **library** gem — let each consumer resolve against
+their own dependency graph.
+
+## Publishing to RubyGems
+
+```bash
+gem build tally.gemspec          # produces tally-0.1.0.gem
+gem push tally-0.1.0.gem         # uploads to rubygems.org (needs an account + MFA)
+```
+
+`bundle exec rake release` automates tag + build + push when the Rakefile uses the
+Bundler gem tasks.
+
+## Rakefile with a test task
+
+```ruby
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test
+```
+
+Run with `bundle exec rake test` (or just `bundle exec rake`).
+
+## Minitest, full file
+
+Minitest ships with Ruby. Both an `assert`-style and a spec-style exist; assert-style
+is the low-ceremony default.
+
+```ruby
+# test/tally_test.rb
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "tally"
+
+class TallyTest < Minitest::Test
+  def setup
+    @sentence = "the cat the hat the"
+  end
+
+  def test_counts_each_word
+    assert_equal({ "the" => 3, "cat" => 1, "hat" => 1 }, Tally.count(@sentence))
+  end
+
+  def test_empty_string_is_empty_hash
+    assert_empty Tally.count("")
+  end
+
+  def test_raises_on_nil
+    assert_raises(TypeError) { Tally.count(nil) }
+  end
+end
+```
+
+## RSpec, full spec
+
+RSpec is the dominant third-party DSL. Use `let` for lazy fixtures, `subject` for the
+object under test, and `context` to group scenarios.
+
+```ruby
+# spec/tally_spec.rb
+# frozen_string_literal: true
+
+require "tally"
+
+RSpec.describe Tally do
+  describe ".count" do
+    subject(:counts) { described_class.count(sentence) }
+
+    context "with repeated words" do
+      let(:sentence) { "the cat the hat the" }
+
+      it { is_expected.to include("the" => 3) }
+      it { is_expected.to eq("the" => 3, "cat" => 1, "hat" => 1) }
+    end
+
+    context "with an empty string" do
+      let(:sentence) { "" }
+
+      it { is_expected.to be_empty }
+    end
+
+    context "with nil" do
+      let(:sentence) { nil }
+
+      it "raises" do
+        expect { counts }.to raise_error(TypeError)
+      end
+    end
+  end
+end
+```
+
+Run with `bundle exec rspec`. Add a `.rspec` file with `--require spec_helper` to load
+shared config.
+
+## The implementation, idiomatically
+
+The gem these tests describe — note `each_with_object`/`tally`, the magic comment, and
+the module namespace, with no metaprogramming:
+
+```ruby
+# lib/tally.rb
+# frozen_string_literal: true
+
+require_relative "tally/version"
+
+module Tally
+  def self.count(text)
+    text.split.tally          # Enumerable#tally does the whole job
+  end
+end
+```
+
+## RuboCop vs Standard
+
+```yaml
+# .rubocop.yml — full control, every cop tunable
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+Metrics/MethodLength:
+  Max: 15
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+```
+
+```ruby
+# Gemfile — zero-config alternative; no config file to bikeshed
+gem "standard", group: :development
+# run: bundle exec standardrb
+```
+
+Pick **Standard** when you want to end style arguments; pick **RuboCop** when the team
+wants to dial individual cops. Run whichever in CI as a non-negotiable gate.