rubyn-code 0.1.0

data/skills/ruby/strings.md

@@ -0,0 +1,177 @@
+# Ruby: String Handling
+
+## Pattern
+
+Strings are everywhere in Ruby. Use the right tool: frozen string literals for performance, heredocs for multi-line, interpolation for building, and `String` methods over regex when possible.
+
+### Frozen String Literals
+
+```ruby
+# frozen_string_literal: true
+
+# This magic comment at the top of the file freezes ALL string literals
+# Frozen strings can't be mutated, which prevents bugs and improves performance
+# (Ruby can reuse the same object instead of allocating new ones)
+
+name = "Alice"
+name << " Smith"  # => FrozenError: can't modify frozen String
+
+# When you need a mutable string, use .dup or unary +
+name = +"Alice"       # Mutable copy
+name = "Alice".dup    # Same thing, more explicit
+name << " Smith"      # Works
+
+# RECOMMENDATION: Add `# frozen_string_literal: true` to every Ruby file.
+# Rubocop enforces this by default. Rails 8 enables it in new apps.
+```
+
+### Interpolation vs Concatenation vs Format
+
+```ruby
+user = "Alice"
+count = 3
+
+# GOOD: Interpolation — clearest for simple cases
+"Hello, #{user}! You have #{count} orders."
+
+# GOOD: Format for precise number formatting
+format("Total: $%.2f", total / 100.0)       # => "Total: $19.99"
+format("Order %06d", order_id)               # => "Order 000042"
+format("%s has %d orders", user, count)      # => "Alice has 3 orders"
+
+# BAD: Concatenation — ugly, slow, error-prone with non-strings
+"Hello, " + user + "! You have " + count.to_s + " orders."
+
+# BAD: String interpolation for SQL (security vulnerability)
+User.where("name = '#{params[:name]}'")     # SQL INJECTION!
+User.where("name = ?", params[:name])        # Safe: parameterized
+```
+
+### Heredocs
+
+```ruby
+# Plain heredoc — preserves indentation literally
+sql = <<-SQL
+  SELECT *
+  FROM orders
+  WHERE status = 'pending'
+SQL
+
+# Squiggly heredoc (Ruby 2.3+) — strips leading whitespace based on the least-indented line
+message = <<~MSG
+  Hello #{user.name},
+
+  Your order #{order.reference} has shipped!
+  Expected delivery: #{order.estimated_delivery.strftime("%B %d")}.
+
+  Thanks,
+  The Rubyn Team
+MSG
+# Result has no leading spaces — perfect for emails and templates
+
+# Frozen heredoc
+QUERY = <<~SQL.freeze
+  SELECT users.email, COUNT(orders.id) as order_count
+  FROM users
+  LEFT JOIN orders ON orders.user_id = users.id
+  GROUP BY users.email
+SQL
+```
+
+### Common String Operations
+
+```ruby
+# Presence and blank checks (Rails)
+name = "  "
+name.blank?     # => true (whitespace only)
+name.present?   # => false
+name.presence   # => nil (returns nil if blank, self if present)
+
+# Use .presence for conditional assignment
+display_name = user.nickname.presence || user.email
+# Instead of: user.nickname.blank? ? user.email : user.nickname
+
+# Stripping and squishing
+"  hello  world  ".strip       # => "hello  world" (leading/trailing only)
+"  hello  world  ".squish      # => "hello world" (Rails — collapses internal whitespace too)
+
+# Case conversion
+"hello_world".camelize         # => "HelloWorld" (Rails)
+"HelloWorld".underscore        # => "hello_world" (Rails)
+"hello world".titleize         # => "Hello World" (Rails)
+"HELLO".downcase               # => "hello"
+"hello".upcase                 # => "HELLO"
+
+# Checking content
+"hello world".include?("world")         # => true
+"hello world".start_with?("hello")      # => true
+"hello world".end_with?("world")        # => true
+"hello world".match?(/\d/)              # => false (no digits)
+
+# Extracting
+"user@example.com".split("@")          # => ["user", "example.com"]
+"ORD-001-2026".split("-", 2)           # => ["ORD", "001-2026"] (limit splits)
+"hello world"[0..4]                     # => "hello"
+"order_12345".delete_prefix("order_")   # => "12345" (Ruby 2.5+)
+"file.rb".delete_suffix(".rb")          # => "file" (Ruby 2.5+)
+
+# Replacing
+"hello world".sub("world", "Ruby")      # => "hello Ruby" (first occurrence)
+"aabaa".gsub("a", "x")                  # => "xxbxx" (all occurrences)
+"hello world".tr("aeiou", "*")          # => "h*ll* w*rld" (character-level replace)
+
+# Truncation (Rails)
+"A very long description that goes on and on".truncate(30)
+# => "A very long description tha..."
+"A very long description".truncate(20, separator: " ")
+# => "A very long..."  (breaks at word boundary)
+
+# Parameterize for URLs (Rails)
+"Hello World! It's great.".parameterize  # => "hello-world-it-s-great"
+```
+
+### String Building for Performance
+
+```ruby
+# BAD: Repeated concatenation (creates new string objects each time)
+result = ""
+items.each { |item| result += "#{item.name}: #{item.price}\n" }
+
+# GOOD: Array join (one allocation at the end)
+result = items.map { |item| "#{item.name}: #{item.price}" }.join("\n")
+
+# GOOD: StringIO for large outputs
+require "stringio"
+buffer = StringIO.new
+items.each { |item| buffer.puts "#{item.name}: #{item.price}" }
+result = buffer.string
+
+# GOOD: String interpolation with Array for building
+parts = []
+parts << "Status: #{order.status}"
+parts << "Total: #{order.formatted_total}"
+parts << "Items: #{order.line_items.count}" if order.line_items.loaded?
+parts.join(" | ")
+```
+
+## Why This Is Good
+
+- **Frozen string literals prevent mutation bugs and improve performance.** A frozen string used as a hash key or constant is allocated once and reused.
+- **Interpolation is the Ruby way.** `"Hello, #{name}"` is cleaner, safer, and faster than concatenation.
+- **Squiggly heredocs keep code clean.** Multi-line strings stay properly indented in the source without extra whitespace in the output.
+- **`.presence` eliminates conditional checks.** One method replaces a blank-check ternary.
+- **Array + join beats repeated concatenation.** Concatenation creates N intermediate string objects. Join creates one.
+
+## When To Apply
+
+- **`# frozen_string_literal: true`** — every Ruby file, always.
+- **Heredocs** — any string longer than 2 lines.
+- **`.presence`** — any `x.blank? ? default : x` pattern.
+- **`.parameterize`** — any user input going into a URL slug.
+- **`format`** — any numeric formatting (currency, percentages, padded numbers).
+
+## When NOT To Apply
+
+- **Don't over-optimize string building.** For 5-10 concatenations, readability wins over performance. `join` matters when you have 1,000+ items.
+- **Don't use `.squish` on content that should preserve whitespace** — code blocks, pre-formatted text, etc.
+- **Don't freeze mutable strings.** If you're building a string incrementally, don't freeze the initial value.

data/skills/ruby_project/bundler_dependencies.md

@@ -0,0 +1,181 @@
+# Ruby: Bundler and Dependency Management
+
+## Pattern
+
+Use Bundler to manage dependencies. Pin versions carefully, group gems by environment, audit for vulnerabilities, and keep the Gemfile organized and commented.
+
+### Gemfile Organization
+
+```ruby
+source "https://rubygems.org"
+ruby "~> 3.3"
+
+# ─── Core ───────────────────────────────────────────
+gem "rails", "~> 8.0"
+gem "pg", "~> 1.5"
+gem "redis", "~> 5.0"
+gem "puma", "~> 6.0"
+
+# ─── Authentication & Authorization ─────────────────
+gem "devise", "~> 4.9"
+gem "pundit", "~> 2.3"
+
+# ─── Background Jobs ────────────────────────────────
+gem "sidekiq", "~> 7.2"
+gem "sidekiq-cron", "~> 1.12"
+
+# ─── API ─────────────────────────────────────────────
+gem "grape", "~> 2.0"
+gem "grape-entity", "~> 1.0"
+
+# ─── External Services ──────────────────────────────
+gem "faraday", "~> 2.9"
+gem "anthropic", "~> 0.3"      # Claude API client
+gem "stripe", "~> 10.0"
+
+# ─── Frontend ────────────────────────────────────────
+gem "turbo-rails", "~> 2.0"
+gem "stimulus-rails", "~> 1.3"
+gem "tailwindcss-rails", "~> 2.6"
+
+group :development, :test do
+  gem "debug"                   # Built-in Ruby debugger
+  gem "dotenv-rails"            # Load .env in development
+  gem "factory_bot_rails"       # Test factories
+  gem "faker"                   # Generate fake data for seeds
+end
+
+group :development do
+  gem "bullet"                  # N+1 query detection
+  gem "rack-mini-profiler"      # Performance profiling
+  gem "web-console"             # In-browser Rails console
+  gem "rubocop-rails-omakase"   # Rails-recommended linting
+  gem "annotate"                # Schema annotations on models
+  gem "strong_migrations"       # Catch unsafe migrations
+end
+
+group :test do
+  gem "capybara"                # System tests
+  gem "selenium-webdriver"      # Browser driver
+  gem "webmock"                 # Stub HTTP requests
+  gem "simplecov", require: false  # Test coverage
+  gem "mocha"                   # Mocking for Minitest
+end
+
+group :production do
+  # Production-only gems (monitoring, APM)
+end
+```
+
+### Version Constraints
+
+```ruby
+# Pessimistic operator (~>) — the RIGHT default
+gem "rails", "~> 8.0"       # >= 8.0.0, < 9.0 (major updates require manual bump)
+gem "pg", "~> 1.5"          # >= 1.5.0, < 2.0
+gem "sidekiq", "~> 7.2"     # >= 7.2.0, < 8.0
+
+# Exact pin — for gems where ANY update could break you
+gem "anthropic", "0.3.2"    # Exactly this version
+
+# No constraint — AVOID (accepts any version, including breaking changes)
+gem "faraday"               # BAD: could jump from 2.x to 3.x on bundle update
+
+# Greater than — rarely needed
+gem "ruby", ">= 3.1"       # For gemspecs only, not Gemfiles
+```
+
+### Security Auditing
+
+```bash
+# Check for known vulnerabilities in your dependencies
+gem install bundler-audit
+bundle audit check --update
+
+# Output:
+# Name: actionpack
+# Version: 7.0.4
+# CVE: CVE-2023-22795
+# Criticality: High
+# Solution: upgrade to ~> 7.0.4.1
+
+# Automate in CI
+# .github/workflows/security.yml
+# - run: bundle audit check --update
+```
+
+### Bundle Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Update a specific gem
+bundle update sidekiq
+
+# Update all gems within constraints
+bundle update
+
+# Show where a gem is installed
+bundle show faraday
+
+# Show dependency tree
+bundle list
+
+# Open a gem's source code in your editor
+bundle open faraday
+
+# Check for outdated gems
+bundle outdated
+
+# Verify Gemfile.lock matches Gemfile
+bundle check
+```
+
+### Gemfile.lock — Always Commit It
+
+```
+# For APPLICATIONS (Rails apps, Sinatra apps):
+# ✅ ALWAYS commit Gemfile.lock
+# Ensures every developer and CI runs the exact same versions
+
+# For GEMS (libraries you publish):
+# ❌ Do NOT commit Gemfile.lock
+# Add to .gitignore — consumers use their own lock file
+# The gemspec defines version constraints, not exact versions
+```
+
+## Why This Is Good
+
+- **Pessimistic version constraints prevent breaking changes.** `~> 8.0` allows patch and minor updates but blocks major version jumps that could break your app.
+- **Groups keep production lean.** Development gems (bullet, rubocop) don't install on production servers.
+- **Comments explain WHY a gem exists.** Future developers know what `anthropic` does without looking it up.
+- **`bundle audit` catches CVEs.** Known vulnerabilities in dependencies are reported before they reach production.
+- **Gemfile.lock ensures reproducibility.** Every environment runs the exact same gem versions.
+
+## Anti-Pattern
+
+```ruby
+# BAD: No version constraints
+gem "rails"
+gem "pg"
+gem "sidekiq"
+
+# BAD: All gems in one ungrouped list
+gem "rails"
+gem "debug"       # Dev only — shouldn't install in production
+gem "pg"
+gem "capybara"    # Test only
+gem "sidekiq"
+gem "webmock"     # Test only
+
+# BAD: Not committing Gemfile.lock
+# .gitignore
+Gemfile.lock      # DON'T DO THIS for applications
+```
+
+## When To Apply
+
+- **Every Ruby project.** Bundler is non-negotiable. Use it from the first line of code.
+- **Run `bundle audit` in CI.** Every build should check for vulnerabilities.
+- **Update dependencies monthly.** `bundle outdated` → update one gem at a time → run tests → commit.

data/skills/ruby_project/cli_tools.md

@@ -0,0 +1,224 @@
+# Ruby: CLI Tools with Thor
+
+## Pattern
+
+Thor is the CLI framework Rails uses internally. It provides command parsing, subcommands, options, and help generation. Use it for any Ruby CLI tool that has more than 2-3 commands.
+
+```ruby
+# lib/rubyn/cli.rb
+require "thor"
+
+module Rubyn
+  class CLI < Thor
+    desc "init", "Initialize Rubyn in the current project"
+    option :api_key, type: :string, desc: "API key (or set RUBYN_API_KEY env var)"
+    def init
+      api_key = options[:api_key] || ENV["RUBYN_API_KEY"]
+      api_key ||= ask("Enter your Rubyn API key:")
+
+      result = Commands::Init.call(api_key: api_key, project_dir: Dir.pwd)
+
+      if result.success?
+        say "✅ Rubyn initialized.", :green
+        say "   #{result.project_info}", :cyan
+      else
+        say "❌ #{result.error}", :red
+        exit 1
+      end
+    end
+
+    desc "refactor FILE", "Refactor a file toward best practices"
+    option :model, type: :string, default: "base", enum: %w[light base pro], desc: "AI model tier"
+    option :apply, type: :boolean, default: false, desc: "Auto-apply changes without prompting"
+    def refactor(file_path)
+      ensure_initialized!
+      ensure_file_exists!(file_path)
+
+      say "🔍 Analyzing #{file_path}...", :cyan
+      context = Context::FileResolver.resolve(file_path, project_dir: Dir.pwd)
+      say "   Loading context: #{context.related_files.map { |f| File.basename(f) }.join(', ')}"
+
+      result = Commands::Refactor.call(
+        file_path: file_path,
+        model_tier: options[:model],
+        context: context
+      )
+
+      display_streaming_response(result)
+      display_credits(result)
+
+      if options[:apply] || yes?("Apply changes? (y/n)")
+        apply_changes(result.changes)
+        say "✅ Changes applied.", :green
+      else
+        say "Changes discarded.", :yellow
+      end
+    end
+
+    desc "spec FILE", "Generate tests for a file"
+    option :model, type: :string, default: "base", enum: %w[light base pro]
+    option :framework, type: :string, enum: %w[rspec minitest], desc: "Override detected test framework"
+    def spec(file_path)
+      ensure_initialized!
+      ensure_file_exists!(file_path)
+
+      say "🧪 Generating tests for #{file_path}...", :cyan
+      result = Commands::Spec.call(file_path: file_path, model_tier: options[:model])
+
+      display_streaming_response(result)
+      display_credits(result)
+
+      if yes?("Write spec file? (y/n)")
+        write_file(result.spec_path, result.spec_content)
+        say "✅ Written to #{result.spec_path}", :green
+      end
+    end
+
+    desc "review FILE_OR_DIR", "Review code for anti-patterns"
+    option :model, type: :string, default: "base", enum: %w[light base pro]
+    def review(path)
+      ensure_initialized!
+
+      files = File.directory?(path) ? Dir.glob("#{path}/**/*.rb") : [path]
+      say "🔍 Reviewing #{files.count} file(s)...", :cyan
+
+      result = Commands::Review.call(files: files, model_tier: options[:model])
+      display_streaming_response(result)
+      display_credits(result)
+    end
+
+    desc "usage", "Show credit balance and recent activity"
+    def usage
+      ensure_initialized!
+
+      result = Commands::Usage.call
+      say result.formatted_output
+    end
+
+    desc "version", "Show Rubyn version"
+    def version
+      say "Rubyn #{Rubyn::VERSION}"
+    end
+
+    desc "dashboard", "Open the Rubyn web dashboard"
+    def dashboard
+      if File.exist?(File.join(Dir.pwd, "config", "routes.rb"))
+        say "Dashboard available at http://localhost:3000/rubyn", :cyan
+        say "(Make sure your Rails server is running)"
+      else
+        say "Starting standalone dashboard...", :cyan
+        Commands::Dashboard.call(project_dir: Dir.pwd)
+      end
+    end
+
+    private
+
+    def ensure_initialized!
+      unless Rubyn::Config.initialized?
+        say "❌ Rubyn not initialized. Run `rubyn init` first.", :red
+        exit 1
+      end
+    end
+
+    def ensure_file_exists!(path)
+      unless File.exist?(path)
+        say "❌ File not found: #{path}", :red
+        exit 1
+      end
+    end
+
+    def display_streaming_response(result)
+      # StreamHandler renders content in real-time via SSE
+      result.stream.each do |chunk|
+        print chunk.text  # Streams to terminal as it arrives
+      end
+      puts
+    end
+
+    def display_credits(result)
+      say "📊 Used #{result.credits_used} credits (#{result.model_tier}) — #{result.balance_remaining} remaining", :cyan
+    end
+
+    def apply_changes(changes)
+      changes.each do |change|
+        write_file(change.path, change.content)
+      end
+    end
+
+    def write_file(path, content)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, content)
+    end
+  end
+end
+```
+
+### The Executable
+
+```ruby
+#!/usr/bin/env ruby
+# exe/rubyn
+
+require "rubyn"
+Rubyn::CLI.start(ARGV)
+```
+
+### Gemspec Setup
+
+```ruby
+# rubyn.gemspec
+spec.executables = ["rubyn"]
+spec.bindir = "exe"
+```
+
+### Thor Features Used
+
+```ruby
+# Options
+option :verbose, type: :boolean, default: false, aliases: "-v"
+option :output, type: :string, default: "terminal", enum: %w[terminal json file]
+option :count, type: :numeric, default: 10
+
+# Ask for input
+name = ask("What is your name?")
+password = ask("Password:", echo: false)  # Hidden input
+
+# Yes/No confirmation
+if yes?("Are you sure?")
+  # proceed
+end
+
+# Colored output
+say "Success!", :green
+say "Warning!", :yellow
+say "Error!", :red
+say "Info", :cyan
+
+# Tables
+print_table([
+  ["Model", "Credits", "Status"],
+  ["Base", "3", "✅"],
+  ["Pro", "7", "✅"]
+])
+
+# Shell commands
+run("bundle exec rspec #{spec_path}")  # Runs and shows output
+```
+
+## Why This Is Good
+
+- **Auto-generated help.** `rubyn help`, `rubyn help refactor` — Thor generates help text from `desc` and `option` declarations.
+- **Type-checked options.** `type: :boolean`, `type: :numeric`, `enum: %w[light base pro]` — Thor validates before your code runs.
+- **Consistent interface.** Every CLI tool built with Thor follows the same patterns. Users familiar with Rails generators, Bundler, or any Thor-based CLI feel at home.
+- **Subcommands for free.** Each `desc` + method becomes a subcommand. No routing logic, no argument parsing.
+- **Testable.** `Rubyn::CLI.start(["refactor", "app/controllers/orders_controller.rb", "--model", "pro"])` — invoke CLI commands programmatically in tests.
+
+## When To Apply
+
+- **Any CLI tool with 3+ commands.** Thor provides structure, help, and option parsing that OptionParser requires you to build manually.
+- **Gem executables.** Thor is the standard for Ruby gem CLIs (Rails, Bundler, Rubocop all use it).
+
+## When NOT To Apply
+
+- **One-off scripts.** A single-purpose script doesn't need Thor. Use `OptionParser` or just `ARGV`.
+- **Two commands.** If the CLI is literally `tool do_thing` and `tool --version`, Thor is overkill.