rubyn-code 0.1.0

data/lib/rubyn_code.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require_relative "rubyn_code/version"
+
+module RubynCode
+  class Error < StandardError; end
+  class AuthenticationError < Error; end
+  class BudgetExceededError < Error; end
+  class PermissionDeniedError < Error; end
+  class StallDetectedError < Error; end
+  class ToolNotFoundError < Error; end
+  class ConfigError < Error; end
+
+  # Infrastructure
+  autoload :Config, "rubyn_code/config/settings"
+
+  # Database
+  module DB
+    autoload :Connection, "rubyn_code/db/connection"
+    autoload :Migrator, "rubyn_code/db/migrator"
+    autoload :Schema, "rubyn_code/db/schema"
+  end
+
+  # Auth
+  module Auth
+    autoload :OAuth, "rubyn_code/auth/oauth"
+    autoload :TokenStore, "rubyn_code/auth/token_store"
+    autoload :Server, "rubyn_code/auth/server"
+  end
+
+  # LLM
+  module LLM
+    autoload :Client, "rubyn_code/llm/client"
+    autoload :Streaming, "rubyn_code/llm/streaming"
+    autoload :MessageBuilder, "rubyn_code/llm/message_builder"
+  end
+
+  # Layer 1: Agent Loop
+  module Agent
+    autoload :Loop, "rubyn_code/agent/loop"
+    autoload :LoopDetector, "rubyn_code/agent/loop_detector"
+    autoload :Conversation, "rubyn_code/agent/conversation"
+  end
+
+  # Layer 2: Tool System
+  module Tools
+    autoload :Base, "rubyn_code/tools/base"
+    autoload :Registry, "rubyn_code/tools/registry"
+    autoload :Schema, "rubyn_code/tools/schema"
+    autoload :Executor, "rubyn_code/tools/executor"
+    autoload :ReadFile, "rubyn_code/tools/read_file"
+    autoload :WriteFile, "rubyn_code/tools/write_file"
+    autoload :EditFile, "rubyn_code/tools/edit_file"
+    autoload :Glob, "rubyn_code/tools/glob"
+    autoload :Grep, "rubyn_code/tools/grep"
+    autoload :Bash, "rubyn_code/tools/bash"
+    autoload :RailsGenerate, "rubyn_code/tools/rails_generate"
+    autoload :DbMigrate, "rubyn_code/tools/db_migrate"
+    autoload :RunSpecs, "rubyn_code/tools/run_specs"
+    autoload :BundleInstall, "rubyn_code/tools/bundle_install"
+    autoload :BundleAdd, "rubyn_code/tools/bundle_add"
+    autoload :Compact, "rubyn_code/tools/compact"
+    autoload :LoadSkill, "rubyn_code/tools/load_skill"
+    autoload :Task, "rubyn_code/tools/task"
+    autoload :MemorySearch, "rubyn_code/tools/memory_search"
+    autoload :MemoryWrite, "rubyn_code/tools/memory_write"
+    autoload :SendMessage, "rubyn_code/tools/send_message"
+    autoload :ReadInbox, "rubyn_code/tools/read_inbox"
+    autoload :ReviewPr, "rubyn_code/tools/review_pr"
+    autoload :SpawnAgent, "rubyn_code/tools/spawn_agent"
+    autoload :BackgroundRun, "rubyn_code/tools/background_run"
+    autoload :WebSearch, "rubyn_code/tools/web_search"
+    autoload :WebFetch, "rubyn_code/tools/web_fetch"
+    autoload :GitCommit, "rubyn_code/tools/git_commit"
+    autoload :GitDiff, "rubyn_code/tools/git_diff"
+    autoload :GitLog, "rubyn_code/tools/git_log"
+    autoload :GitStatus, "rubyn_code/tools/git_status"
+    autoload :SpawnTeammate, "rubyn_code/tools/spawn_teammate"
+  end
+
+  # Layer 3: Permissions
+  module Permissions
+    autoload :Tier, "rubyn_code/permissions/tier"
+    autoload :Policy, "rubyn_code/permissions/policy"
+    autoload :DenyList, "rubyn_code/permissions/deny_list"
+    autoload :Prompter, "rubyn_code/permissions/prompter"
+  end
+
+  # Layer 4: Context Management
+  module Context
+    autoload :Manager, "rubyn_code/context/manager"
+    autoload :Compactor, "rubyn_code/context/compactor"
+    autoload :MicroCompact, "rubyn_code/context/micro_compact"
+    autoload :AutoCompact, "rubyn_code/context/auto_compact"
+    autoload :ManualCompact, "rubyn_code/context/manual_compact"
+  end
+
+  # Layer 5: Skills
+  module Skills
+    autoload :Loader, "rubyn_code/skills/loader"
+    autoload :Catalog, "rubyn_code/skills/catalog"
+    autoload :Document, "rubyn_code/skills/document"
+  end
+
+  # Layer 6: Sub-Agents
+  module SubAgents
+    autoload :Runner, "rubyn_code/sub_agents/runner"
+    autoload :Summarizer, "rubyn_code/sub_agents/summarizer"
+  end
+
+  # Layer 7: Tasks
+  module Tasks
+    autoload :Manager, "rubyn_code/tasks/manager"
+    autoload :DAG, "rubyn_code/tasks/dag"
+    autoload :Models, "rubyn_code/tasks/models"
+  end
+
+  # Layer 8: Background
+  module Background
+    autoload :Worker, "rubyn_code/background/worker"
+    autoload :Job, "rubyn_code/background/job"
+    autoload :Notifier, "rubyn_code/background/notifier"
+  end
+
+  # Layer 9: Teams
+  module Teams
+    autoload :Manager, "rubyn_code/teams/manager"
+    autoload :Mailbox, "rubyn_code/teams/mailbox"
+    autoload :Teammate, "rubyn_code/teams/teammate"
+  end
+
+  # Layer 10: Protocols
+  module Protocols
+    autoload :ShutdownHandshake, "rubyn_code/protocols/shutdown_handshake"
+    autoload :PlanApproval, "rubyn_code/protocols/plan_approval"
+    autoload :InterruptHandler, "rubyn_code/protocols/interrupt_handler"
+  end
+
+  # Layer 11: Autonomous
+  module Autonomous
+    autoload :Daemon, "rubyn_code/autonomous/daemon"
+    autoload :IdlePoller, "rubyn_code/autonomous/idle_poller"
+    autoload :TaskClaimer, "rubyn_code/autonomous/task_claimer"
+  end
+
+  # Layer 12: Memory
+  module Memory
+    autoload :Store, "rubyn_code/memory/store"
+    autoload :Search, "rubyn_code/memory/search"
+    autoload :SessionPersistence, "rubyn_code/memory/session_persistence"
+    autoload :Models, "rubyn_code/memory/models"
+  end
+
+  # Layer 13: Observability
+  module Observability
+    autoload :TokenCounter, "rubyn_code/observability/token_counter"
+    autoload :CostCalculator, "rubyn_code/observability/cost_calculator"
+    autoload :BudgetEnforcer, "rubyn_code/observability/budget_enforcer"
+    autoload :UsageReporter, "rubyn_code/observability/usage_reporter"
+    autoload :Models, "rubyn_code/observability/models"
+  end
+
+  # Layer 14: Hooks
+  module Hooks
+    autoload :Registry, "rubyn_code/hooks/registry"
+    autoload :Runner, "rubyn_code/hooks/runner"
+    autoload :BuiltIn, "rubyn_code/hooks/built_in"
+    autoload :UserHooks, "rubyn_code/hooks/user_hooks"
+  end
+
+  # Layer 15: MCP
+  module MCP
+    autoload :Client, "rubyn_code/mcp/client"
+    autoload :StdioTransport, "rubyn_code/mcp/stdio_transport"
+    autoload :SSETransport, "rubyn_code/mcp/sse_transport"
+    autoload :ToolBridge, "rubyn_code/mcp/tool_bridge"
+    autoload :Config, "rubyn_code/mcp/config"
+  end
+
+  # Layer 16: Learning
+  module Learning
+    autoload :Extractor, "rubyn_code/learning/extractor"
+    autoload :Instinct, "rubyn_code/learning/instinct"
+    autoload :InstinctMethods, "rubyn_code/learning/instinct"
+    autoload :Injector, "rubyn_code/learning/injector"
+  end
+
+  # CLI
+  module CLI
+    autoload :App, "rubyn_code/cli/app"
+    autoload :REPL, "rubyn_code/cli/repl"
+    autoload :InputHandler, "rubyn_code/cli/input_handler"
+    autoload :Renderer, "rubyn_code/cli/renderer"
+    autoload :Spinner, "rubyn_code/cli/spinner"
+    autoload :StreamFormatter, "rubyn_code/cli/stream_formatter"
+  end
+
+  # Output
+  module Output
+    autoload :Formatter, "rubyn_code/output/formatter"
+    autoload :DiffRenderer, "rubyn_code/output/diff_renderer"
+  end
+end

data/skills/code_quality/fits_in_your_head.md

@@ -0,0 +1,189 @@
+# Code Quality: Code That Fits in Your Head
+
+## Core Principle
+
+The human brain can hold approximately 7 items in working memory at once. Code should be structured so that understanding any single unit (method, class, module) requires holding fewer than 7 concepts simultaneously. When code exceeds working memory limits, bugs creep in because developers can't track all the moving parts.
+
+## The 7±2 Rule Applied to Code
+
+### Methods: Max 7 Lines of Logic
+
+A method should fit in your mental "scratchpad." If you can't hold the entire method in your head at once, it's too complex.
+
+```ruby
+# GOOD: 5 concepts — easily fits in working memory
+# 1. Load order  2. Check editable  3. Update  4. Success path  5. Failure path
+def update
+  order = current_user.orders.find(params[:id])
+  return head :forbidden unless order.editable?
+
+  if order.update(order_params)
+    redirect_to order, notice: "Updated."
+  else
+    render :edit, status: :unprocessable_entity
+  end
+end
+
+# BAD: 12+ concepts — exceeds working memory
+def update
+  order = current_user.orders.find(params[:id])
+  return head :forbidden unless order.editable?
+
+  old_total = order.total
+  order.assign_attributes(order_params)
+
+  order.line_items.each do |item|
+    product = Product.find(item.product_id)
+    if product.stock < item.quantity
+      order.errors.add(:base, "#{product.name} insufficient stock")
+    end
+    item.unit_price = product.current_price  # Price may have changed
+  end
+
+  order.subtotal = order.line_items.sum { |li| li.quantity * li.unit_price }
+  order.tax = TaxService.calculate(order.subtotal, order.shipping_address)
+  order.total = order.subtotal + order.tax
+
+  if order.total != old_total && order.paid?
+    difference = order.total - old_total
+    if difference > 0
+      Payments::ChargeService.call(order, difference)
+    else
+      Payments::RefundService.call(order, difference.abs)
+    end
+  end
+
+  if order.errors.empty? && order.save
+    OrderMailer.updated(order).deliver_later if order.total != old_total
+    redirect_to order, notice: "Updated."
+  else
+    render :edit, status: :unprocessable_entity
+  end
+end
+```
+
+The second method requires tracking: order, old_total, line_items, products, stock levels, pricing changes, subtotal, tax, total, paid status, payment difference, charge vs refund, email condition, save result. That's 13+ concepts — far beyond working memory.
+
+### Classes: Max 7 Public Methods
+
+A class with 3-7 public methods is graspable. You can understand its entire interface at a glance. Beyond 7, you start forgetting methods while reading others.
+
+```ruby
+# GOOD: 5 public methods — clear, focused interface
+class Order < ApplicationRecord
+  # Queries
+  scope :recent, -> { where(created_at: 30.days.ago..) }
+  scope :pending, -> { where(status: :pending) }
+
+  # Commands
+  def confirm!
+    current_state.confirm(self)
+  end
+
+  def cancel!(reason:)
+    current_state.cancel(self, reason: reason)
+  end
+
+  # Queries
+  def total
+    line_items.sum { |li| li.quantity * li.unit_price }
+  end
+
+  def editable?
+    pending? || confirmed?
+  end
+end
+```
+
+### Parameters: Max 3-4
+
+After 4 parameters, callers start confusing argument order, even with keyword arguments. Extract a parameter object or rethink the method's responsibility.
+
+```ruby
+# GOOD: 2 parameters — trivially understandable
+def send_notification(user, message)
+
+# OK: 4 keyword parameters — manageable with names
+def create_order(user:, items:, address:, payment_method:)
+
+# BAD: 7 parameters — nobody can remember these
+def create_order(user:, items:, address:, payment_method:, discount_code:, currency:, notify:)
+
+# FIX: Extract a parameter object
+OrderRequest = Data.define(:user, :items, :address, :payment_method, :discount_code, :currency, :notify)
+def create_order(request)
+```
+
+### Nesting: Max 2 Levels
+
+Each level of nesting adds a context to track. At 3+ levels, you're juggling too many conditions.
+
+```ruby
+# GOOD: 1 level of nesting
+def process(order)
+  return error("Empty") if order.line_items.empty?
+  return error("Invalid address") unless order.address_valid?
+
+  charge(order)
+end
+
+# BAD: 4 levels
+def process(order)
+  if order.line_items.any?
+    if order.address_valid?
+      if order.user.payment_method.present?
+        if order.user.payment_method.valid?
+          charge(order)
+        end
+      end
+    end
+  end
+end
+```
+
+## The Transformation Priority Principle
+
+When your code is complex, simplify in this order:
+
+1. **Extract till you drop.** Break long methods into smaller ones until each method is 5-7 lines.
+2. **Flatten conditionals.** Use guard clauses to eliminate nesting.
+3. **Replace primitives with objects.** Turn strings and hashes into value objects with named methods.
+4. **Replace branching with polymorphism.** Case statements on type become separate classes.
+5. **Compose small objects.** Large classes become coordinators of small, focused collaborators.
+
+## Practical Heuristics
+
+### The Squint Test
+Squint at your code. If the indentation forms a deep "V" shape (deep nesting), it needs flattening. If you see large blocks of similar-looking code, it has duplication.
+
+### The Headline Test
+Can you describe what a method does in a short headline? "Calculates order total" — good. "Validates, calculates, charges, and notifies" — too many verbs, extract.
+
+### The Scroll Test
+If a method or class requires scrolling to read in your editor, it's too long. A method should fit on screen. A class should fit in a few screens.
+
+### The Rename Test
+If you can't think of a good name for a method, it probably does too many things. A method that does one thing always has a clear name. "Process" and "handle" are signs of unfocused methods.
+
+## When To Apply
+
+- **Every code review.** Check: does each method fit in working memory? Can you understand it without scrolling back?
+- **When you re-read code and feel confused.** If you wrote it last week and can't quickly understand it, future-you (and every teammate) will have the same problem.
+- **When modifying existing code.** Before adding a feature to a 50-line method, extract until the method is small, then add the feature to the appropriate extracted method.
+
+## When NOT To Apply
+
+- **Don't optimize for line count.** A 12-line method that reads clearly is better than 4 methods of 3 lines each where you lose the overall flow.
+- **Don't extract if names don't improve clarity.** `do_step_1`, `do_step_2` are worse than inline code. Extract when the method name adds meaning.
+- **Configuration and setup code is naturally longer.** A Rails initializer or a factory definition doesn't need to be 7 lines. The heuristics apply to logic, not configuration.
+
+## Connection to Other Principles
+
+This principle underpins everything else:
+- **SRP** keeps classes small enough to fit in your head
+- **Extract Method** keeps methods small enough to fit in your head
+- **Guard Clauses** reduce nesting to fit in your head
+- **Value Objects** replace primitives so you think in domain terms, not data types
+- **Service Objects** keep controllers small enough to fit in your head
+
+The goal is always the same: any developer should be able to read a unit of code and fully understand it without external aids, notes, or extensive scrolling.

data/skills/code_quality/naming_conventions.md

@@ -0,0 +1,213 @@
+# Code Quality: Naming Conventions
+
+## Pattern
+
+Good names are the cheapest documentation. A well-named method, class, or variable eliminates the need for comments and makes code read like prose. Ruby and Rails have strong naming conventions — follow them.
+
+### Ruby Naming Rules
+
+```ruby
+# Classes and modules: CamelCase (PascalCase)
+class OrderProcessor; end
+module Authenticatable; end
+class Api::V1::OrdersController; end
+
+# Methods and variables: snake_case
+def calculate_total; end
+total_cents = 19_99
+current_user = User.find(session[:user_id])
+
+# Constants: SCREAMING_SNAKE_CASE
+MAX_RETRIES = 3
+DEFAULT_CURRENCY = "USD"
+API_BASE_URL = "https://api.rubyn.ai"
+
+# Predicates (boolean methods): end with ?
+def active?; end
+def can_cancel?; end
+def shipped?; end
+# Returns true/false. Never name it `is_active` or `check_active`.
+
+# Dangerous methods: end with !
+def save!; end       # Raises on failure (vs save which returns false)
+def destroy!; end    # Raises on failure
+def normalize!; end  # Mutates in place (vs normalize which returns new value)
+# ! means "this version does something surprising" — usually raises or mutates.
+
+# Setters: end with =
+def name=(value); end
+attr_writer :name    # Generates name= method
+
+# Private/internal: prefix with _ (convention, not enforced)
+def _build_cache_key; end
+_temp_value = compute_intermediate_step
+```
+
+### Method Naming
+
+```ruby
+# GOOD: Verb for actions, noun for queries
+def create_order(params); end       # Action: does something
+def send_confirmation(order); end   # Action: does something
+def total; end                      # Query: returns a value
+def line_items; end                 # Query: returns a collection
+def pending?; end                   # Predicate: returns boolean
+
+# GOOD: Specific verbs that communicate intent
+def charge_payment(order); end      # Specific: charges
+def validate_inventory(items); end  # Specific: validates
+def generate_reference; end         # Specific: generates
+
+# BAD: Vague verbs that could mean anything
+def process(order); end             # Process how? Does it charge? Ship? Validate?
+def handle(data); end               # Handle what exactly?
+def do_stuff; end                   # Meaningless
+def run; end                        # What does it run?
+def execute; end                    # Same problem
+
+# GOOD: call for service objects (convention)
+class Orders::CreateService
+  def self.call(params, user); end  # .call is the Rails service object convention
+end
+# This works because the CLASS NAME describes the action (CreateService)
+# so .call doesn't need to be more specific
+
+# GOOD: Named constructors for clarity
+Order.from_cart(cart, user: current_user)
+Money.from_dollars(19.99)
+DateRange.parse("2026-01-01..2026-03-20")
+```
+
+### Class Naming
+
+```ruby
+# GOOD: Noun describing what it IS
+class Order; end
+class LineItem; end
+class User; end
+
+# GOOD: Adjective or role for modules (describes capability)
+module Searchable; end
+module Authenticatable; end
+module Sluggable; end
+
+# GOOD: Noun + purpose for service objects
+class Orders::CreateService; end
+class Credits::DeductionService; end
+class Embeddings::CodebaseIndexer; end
+
+# GOOD: Noun + type for specific patterns
+class OrderPresenter; end           # Presenter
+class RegistrationForm; end         # Form object
+class OrdersSearchQuery; end        # Query object
+class StripeAdapter; end            # Adapter
+class EmailNotifier; end            # Notifier
+
+# BAD: Manager, Handler, Processor, Helper (vague — WHAT does it manage?)
+class OrderManager; end             # What aspect of orders?
+class DataHandler; end              # What data? What handling?
+class OrderProcessor; end           # Processes how?
+class OrderHelper; end              # Helps with what?
+
+# FIX: Name the specific responsibility
+class OrderManager → Orders::CreateService + Orders::CancelService
+class DataHandler → CsvImporter + JsonParser
+class OrderProcessor → Orders::FulfillmentService
+```
+
+### Variable Naming
+
+```ruby
+# GOOD: Descriptive, matches the domain
+active_users = User.where(active: true)
+pending_orders = Order.pending
+credit_balance = user.credit_ledger_entries.sum(:amount)
+shipping_address = order.addresses.find_by(type: "shipping")
+
+# GOOD: Plural for collections, singular for individuals
+orders = Order.recent           # Collection
+order = orders.first            # Single item
+line_items = order.line_items   # Collection
+line_item = line_items.first    # Single item
+
+# BAD: Single-letter variables (except in tiny blocks)
+u = User.find(params[:id])     # What's u? 
+o = u.orders.last              # What's o?
+x = o.total * 0.08             # What's x?
+
+# OK: Single-letter in small, obvious blocks
+users.map { |u| u.email }      # OK — the block is 1 line, u is clearly a user
+users.map(&:email)              # BETTER — no variable needed
+
+# BAD: Misleading names
+user_count = User.pluck(:email)        # It's emails, not a count
+is_valid = order.save                  # It's a save result, not a validation check
+temp = Order.where(status: :pending)   # "temp" tells you nothing
+
+# BAD: Hungarian notation or type prefixes
+str_name = "Alice"                     # Ruby doesn't need type prefixes
+arr_items = [1, 2, 3]
+int_count = 5
+hash_config = { timeout: 30 }
+```
+
+### Rails-Specific Conventions
+
+```ruby
+# Controllers: plural noun + Controller
+class OrdersController; end           # Not OrderController
+class Api::V1::UsersController; end
+
+# Models: singular noun
+class Order; end                      # Not Orders
+class LineItem; end                   # Not LineItems
+
+# Tables: plural snake_case (matches model pluralized)
+# orders, line_items, users, credit_ledger_entries
+
+# Foreign keys: singular_model_id
+# order_id, user_id, product_id
+
+# Join tables: alphabetical, both pluralized
+# orders_products, categories_products
+
+# Migrations: verb + noun
+class AddStatusToOrders; end
+class CreateProjectMemberships; end
+class RemoveDeletedAtFromOrders; end
+
+# Jobs: noun + Job
+class OrderConfirmationJob; end
+class CodebaseIndexJob; end
+
+# Mailers: noun + Mailer
+class OrderMailer; end
+class UserMailer; end
+
+# Serializers: singular model + Serializer
+class OrderSerializer; end
+
+# Factories: plural snake_case (matching table)
+# spec/factories/orders.rb
+# spec/factories/line_items.rb
+```
+
+## Why This Is Good
+
+- **Convention eliminates decisions.** When every controller is `PluralNounController` and every service is `Noun::VerbService`, developers don't waste time choosing names. The convention chooses for them.
+- **Names replace comments.** `calculate_shipping_cost` doesn't need a comment explaining what it does. `process` does.
+- **Predictable file locations.** `Orders::CreateService` lives at `app/services/orders/create_service.rb`. The name maps to the path. You can find any class without grep.
+- **`?` and `!` suffixes communicate behavior.** `save` returns false on failure. `save!` raises. The developer knows what to expect from the suffix alone.
+
+## The Rename Test
+
+If you can't think of a good name for a method or class, it probably does too many things. A method that does one thing always has a clear name.
+
+- ❌ `process_order` → What processing? Creating? Shipping? Billing? All three?
+- ✅ `Orders::CreateService`, `Orders::ShipService`, `Orders::BillService`
+
+- ❌ `handle_response` → Handle how?
+- ✅ `parse_json_response`, `validate_response_status`, `extract_order_from_response`
+
+- ❌ `UserManager` → Manages what about users?
+- ✅ `Users::RegistrationService`, `Users::ProfileUpdater`, `Users::DeactivationService`