rubyn-code 0.1.0 → 0.2.0

data/lib/rubyn_code/context/manual_compact.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require "json"
-require "fileutils"
+require 'json'
+require 'fileutils'
 
 module RubynCode
   module Context
@@ -35,7 +35,7 @@ module RubynCode
         instruction = build_instruction(focus)
         summary = request_summary(transcript_text, instruction, llm_client)
 
-        [{ role: "user", content: "[Context compacted — manual]\n\n#{summary}" }]
+        [{ role: 'user', content: "[Context compacted — manual]\n\n#{summary}" }]
       end
 
       def self.build_instruction(focus)
@@ -46,7 +46,7 @@ module RubynCode
 
       def self.save_transcript(messages, dir)
         FileUtils.mkdir_p(dir)
-        timestamp = Time.now.strftime("%Y%m%d_%H%M%S")
+        timestamp = Time.now.strftime('%Y%m%d_%H%M%S')
         path = File.join(dir, "transcript_manual_#{timestamp}.json")
         File.write(path, JSON.pretty_generate(messages))
         path
@@ -62,19 +62,19 @@ module RubynCode
       def self.request_summary(transcript_text, instruction, llm_client)
         summary_messages = [
           {
-            role: "user",
+            role: 'user',
             content: "#{instruction}\n\n---\n\n#{transcript_text}"
           }
         ]
 
         options = {}
-        options[:model] = "claude-sonnet-4-20250514" if llm_client.respond_to?(:chat)
+        options[:model] = 'claude-sonnet-4-20250514' if llm_client.respond_to?(:chat)
 
         response = llm_client.chat(messages: summary_messages, **options)
 
         case response
         when String then response
-        when Hash then response[:content] || response["content"] || response.to_s
+        when Hash then response[:content] || response['content'] || response.to_s
         else
           response.respond_to?(:text) ? response.text : response.to_s
         end

data/lib/rubyn_code/context/micro_compact.rb

@@ -6,7 +6,7 @@ module RubynCode
     # (except the most recent N) with short placeholders to reduce token count
     # without losing conversational continuity.
     module MicroCompact
-      PLACEHOLDER_TEMPLATE = "[Previous: used %<tool_name>s]"
+      PLACEHOLDER_TEMPLATE = '[Previous: used %<tool_name>s]'
       MIN_CONTENT_LENGTH = 100
 
       # Mutates +messages+ in place, replacing old tool_result content with
@@ -16,7 +16,7 @@ module RubynCode
       # @param keep_recent [Integer] number of most-recent tool results to preserve
       # @param preserve_tools [Array<String>] tool names whose results are never compacted
       # @return [Integer] count of compacted tool results
-      def self.call(messages, keep_recent: 3, preserve_tools: ["read_file"])
+      def self.call(messages, keep_recent: 2, preserve_tools: [])
         tool_result_refs = collect_tool_results(messages)
         return 0 if tool_result_refs.size <= keep_recent
 
@@ -32,7 +32,7 @@ module RubynCode
           tool_name = resolve_tool_name(block, tool_name_index)
           next if preserve_tools.include?(tool_name)
 
-          placeholder = format(PLACEHOLDER_TEMPLATE, tool_name: tool_name || "tool")
+          placeholder = format(PLACEHOLDER_TEMPLATE, tool_name: tool_name || 'tool')
           replace_content!(block, placeholder)
           compacted += 1
         end
@@ -48,7 +48,7 @@ module RubynCode
         refs = []
 
         messages.each do |msg|
-          next unless msg[:role] == "user" && msg[:content].is_a?(Array)
+          next unless msg[:role] == 'user' && msg[:content].is_a?(Array)
 
           msg[:content].each_with_index do |block, idx|
             next unless tool_result_block?(block)
@@ -68,12 +68,12 @@ module RubynCode
         index = {}
 
         messages.each do |msg|
-          next unless msg[:role] == "assistant" && msg[:content].is_a?(Array)
+          next unless msg[:role] == 'assistant' && msg[:content].is_a?(Array)
 
           msg[:content].each do |block|
             case block
             when Hash
-              index[block[:id] || block["id"]] = block[:name] || block["name"] if block_type(block) == "tool_use"
+              index[block[:id] || block['id']] = block[:name] || block['name'] if block_type(block) == 'tool_use'
             when LLM::ToolUseBlock
               index[block.id] = block.name
             end
@@ -86,7 +86,7 @@ module RubynCode
       def self.tool_result_block?(block)
         case block
         when Hash
-          block_type(block) == "tool_result"
+          block_type(block) == 'tool_result'
         when LLM::ToolResultBlock
           true
         else
@@ -95,13 +95,13 @@ module RubynCode
       end
 
       def self.block_type(hash)
-        hash[:type] || hash["type"]
+        hash[:type] || hash['type']
       end
 
       def self.extract_content(block)
         case block
         when Hash
-          val = block[:content] || block["content"]
+          val = block[:content] || block['content']
           val.is_a?(String) ? val : val.to_s
         when LLM::ToolResultBlock
           block.content.to_s
@@ -110,7 +110,7 @@ module RubynCode
 
       def self.resolve_tool_name(block, index)
         tool_use_id = case block
-                      when Hash then block[:tool_use_id] || block["tool_use_id"]
+                      when Hash then block[:tool_use_id] || block['tool_use_id']
                       when LLM::ToolResultBlock then block.tool_use_id
                       end
 
@@ -120,10 +120,10 @@ module RubynCode
       def self.replace_content!(block, placeholder)
         case block
         when Hash
-          key = block.key?(:content) ? :content : "content"
+          key = block.key?(:content) ? :content : 'content'
           block[key] = placeholder
         end
-        # Note: Data.define instances are frozen; for ToolResultBlock objects
+        # NOTE: Data.define instances are frozen; for ToolResultBlock objects
         # we rely on messages being stored as hashes in the conversation array.
       end
 

data/lib/rubyn_code/db/RUBYN.md

@@ -0,0 +1,40 @@
+# DB Layer
+
+SQLite connection management and schema migrations.
+
+## Classes
+
+- **`Connection`** — Singleton SQLite3 connection to `~/.rubyn-code/rubyn_code.db`.
+  Creates the directory and database on first access. Configures WAL mode and foreign keys.
+
+- **`Migrator`** — Runs numbered migration files from `db/migrations/`. Tracks applied migrations
+  in `schema_migrations` table. Migrations are idempotent and run in order.
+  Supports two formats:
+  - `.sql` — executed statement-by-statement inside a transaction
+  - `.rb` — Ruby module with `module_function def up(db)` for conditional/complex migrations
+    (e.g. detecting column names via `pragma_table_info` before altering)
+
+- **`Schema`** — Schema introspection utilities. Checks table existence, column info.
+  Used by other layers to verify database state.
+
+## Writing a Ruby Migration
+
+Use `.rb` when you need branching logic that pure SQL can't handle (e.g. schema detection):
+
+```ruby
+# db/migrations/011_fix_something.rb
+module Migration011FixSomething
+  module_function
+
+  def up(db)
+    columns = db.query("SELECT name FROM pragma_table_info('my_table')").to_a
+    column_names = columns.map { |c| c['name'] }
+
+    if column_names.include?('old_column')
+      db.execute("ALTER TABLE my_table RENAME COLUMN old_column TO new_column")
+    end
+  end
+end
+```
+
+Module name is derived from filename: `011_fix_something.rb` → `Migration011FixSomething`.

data/lib/rubyn_code/db/connection.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require "sqlite3"
-require "monitor"
-require "fileutils"
+require 'sqlite3'
+require 'monitor'
+require 'fileutils'
 
 module RubynCode
   module DB
@@ -52,8 +52,8 @@ module RubynCode
         #
         # @yield the block to execute within the transaction
         # @return [Object] the return value of the block
-        def transaction(&block)
-          instance.transaction(&block)
+        def transaction(&)
+          instance.transaction(&)
         end
 
         # Tears down the singleton instance. Intended for test cleanup.
@@ -118,14 +118,14 @@ module RubynCode
           begin
             result = yield
             if @transaction_depth == 1
-              @db.execute("COMMIT")
+              @db.execute('COMMIT')
             else
               @db.execute("RELEASE SAVEPOINT sp_#{@transaction_depth}")
             end
             result
           rescue StandardError => e
             if @transaction_depth == 1
-              @db.execute("ROLLBACK")
+              @db.execute('ROLLBACK')
             else
               @db.execute("ROLLBACK TO SAVEPOINT sp_#{@transaction_depth}")
               @db.execute("RELEASE SAVEPOINT sp_#{@transaction_depth}")
@@ -157,15 +157,15 @@ module RubynCode
 
       def configure_connection
         @db.results_as_hash = true
-        @db.execute("PRAGMA journal_mode = WAL")
-        @db.execute("PRAGMA foreign_keys = ON")
-        @db.execute("PRAGMA busy_timeout = 5000")
-        @db.execute("PRAGMA synchronous = NORMAL")
-        @db.execute("PRAGMA cache_size = -20000") # 20 MB
+        @db.execute('PRAGMA journal_mode = WAL')
+        @db.execute('PRAGMA foreign_keys = ON')
+        @db.execute('PRAGMA busy_timeout = 5000')
+        @db.execute('PRAGMA synchronous = NORMAL')
+        @db.execute('PRAGMA cache_size = -20000') # 20 MB
       end
 
       def begin_top_level_transaction
-        @db.execute("BEGIN IMMEDIATE")
+        @db.execute('BEGIN IMMEDIATE')
       end
 
       def begin_savepoint

data/lib/rubyn_code/db/migrator.rb

@@ -2,11 +2,15 @@
 
 module RubynCode
   module DB
-    # Reads SQL migration files from db/migrations/, tracks applied versions
+    # Reads migration files from db/migrations/, tracks applied versions
     # in a schema_migrations table, and applies new migrations in order.
+    #
+    # Supports two migration formats:
+    # - `.sql` files: executed statement-by-statement inside a transaction
+    # - `.rb` files: loaded and called via `ModuleName.up(connection)`
     class Migrator
       # @return [String] absolute path to the migrations directory
-      MIGRATIONS_DIR = File.expand_path("../../../db/migrations", __dir__).freeze
+      MIGRATIONS_DIR = File.expand_path('../../../db/migrations', __dir__).freeze
 
       # @param connection [Connection] the database connection to migrate
       def initialize(connection)
@@ -34,7 +38,7 @@ module RubynCode
       # @return [Array<Array(Integer, String)>] pairs of [version, file_path]
       def pending_migrations
         applied = applied_versions
-        available_migrations.reject { |version, _| applied.include?(version) }
+        available_migrations.except(*applied)
       end
 
       # Returns the set of already-applied migration versions.
@@ -42,9 +46,9 @@ module RubynCode
       # @return [Set<Integer>]
       def applied_versions
         rows = @connection.query(
-          "SELECT version FROM schema_migrations ORDER BY version"
+          'SELECT version FROM schema_migrations ORDER BY version'
         ).to_a
-        rows.map { |row| row["version"] }.to_set
+        rows.to_set { |row| row['version'] }
       end
 
       # Returns the current schema version (highest applied migration).
@@ -52,20 +56,28 @@ module RubynCode
       # @return [Integer, nil]
       def current_version
         row = @connection.query(
-          "SELECT MAX(version) AS max_version FROM schema_migrations"
+          'SELECT MAX(version) AS max_version FROM schema_migrations'
         ).to_a.first
-        row && row["max_version"]
+        row && row['max_version']
       end
 
       # Lists all available migration files sorted by version.
       #
       # @return [Array<Array(Integer, String)>] pairs of [version, file_path]
       def available_migrations
-        pattern = File.join(MIGRATIONS_DIR, "*.sql")
-        Dir.glob(pattern)
-           .map { |path| parse_migration_file(path) }
-           .compact
-           .sort_by(&:first)
+        all = Dir.glob(File.join(MIGRATIONS_DIR, '*'))
+                 .select { |path| path.end_with?('.sql', '.rb') }
+                 .map { |path| parse_migration_file(path) }
+                 .compact
+
+        # Deduplicate: if both .rb and .sql exist for the same version, prefer .rb
+        by_version = {}
+        all.each do |version, path|
+          existing = by_version[version]
+          by_version[version] = [version, path] if existing.nil? || path.end_with?('.rb')
+        end
+
+        by_version.values.sort_by(&:first)
       end
 
       private
@@ -80,18 +92,42 @@ module RubynCode
       end
 
       def apply_migration(version, path)
-        sql = File.read(path)
         @connection.transaction do
-          # Execute each statement separately (SQLite doesn't support multi-statement execute)
-          split_statements(sql).each do |statement|
-            @connection.execute(statement)
+          if path.end_with?('.rb')
+            apply_ruby_migration(path)
+          else
+            apply_sql_migration(path)
           end
+
           @connection.execute(
-            "INSERT INTO schema_migrations (version) VALUES (?)", [version]
+            'INSERT INTO schema_migrations (version) VALUES (?)', [version]
           )
         end
       end
 
+      def apply_sql_migration(path)
+        sql = File.read(path)
+        split_statements(sql).each do |statement|
+          @connection.execute(statement)
+        end
+      end
+
+      # Loads a Ruby migration file and calls its `.up` method.
+      # The migration module must define `module_function def up(db)`.
+      def apply_ruby_migration(path)
+        require path
+        module_name = extract_module_name(path)
+        mod = Object.const_get(module_name)
+        mod.up(@connection)
+      end
+
+      # Derives the module name from a migration filename.
+      # e.g. "011_fix_mailbox_messages_columns.rb" -> "Migration011FixMailboxMessagesColumns"
+      def extract_module_name(path)
+        basename = File.basename(path, '.rb')
+        "Migration#{basename.split('_').map(&:capitalize).join}"
+      end
+
       # Splits a SQL file into individual statements, handling semicolons
       # inside string literals and ignoring empty/comment-only fragments.
       #
@@ -99,34 +135,37 @@ module RubynCode
       # @return [Array<String>]
       def split_statements(sql)
         statements = []
-        current = +""
+        current = +''
         in_block = false
 
         sql.each_line do |line|
           stripped = line.strip
 
           # Track BEGIN/END blocks (e.g., triggers)
-          in_block = true if stripped.match?(/\bBEGIN\b/i) && !stripped.match?(/\ABEGIN\s+(IMMEDIATE|DEFERRED|EXCLUSIVE)/i)
+          if stripped.match?(/\bBEGIN\b/i) && !stripped.match?(/\ABEGIN\s+(IMMEDIATE|DEFERRED|EXCLUSIVE)/i)
+            in_block = true
+          end
           current << line
 
           if in_block
             if stripped.match?(/\bEND\b\s*;?\s*$/i)
               in_block = false
-              statements << current.strip.chomp(";")
-              current = +""
+              statements << current.strip.chomp(';')
+              current = +''
             end
-          elsif stripped.end_with?(";")
-            stmt = current.strip.chomp(";").strip
+          elsif stripped.end_with?(';')
+            stmt = current.strip.chomp(';').strip
             statements << stmt unless stmt.empty? || (stmt.match?(/\A\s*--/) && !stmt.include?("\n"))
-            current = +""
+            current = +''
           end
         end
 
         # Handle any remaining content
-        remainder = current.strip.chomp(";").strip
+        remainder = current.strip.chomp(';').strip
         statements << remainder unless remainder.empty?
 
-        statements
+        # Filter out comment-only statements
+        statements.reject { |s| s.lines.all? { |l| l.strip.empty? || l.strip.start_with?('--') } }
       end
 
       # Extracts the version number and name from a migration filename.
@@ -134,7 +173,8 @@ module RubynCode
       # @param path [String]
       # @return [Array(Integer, String), nil]
       def parse_migration_file(path)
-        basename = File.basename(path, ".sql")
+        ext = File.extname(path)
+        basename = File.basename(path, ext)
         match = basename.match(/\A(\d+)_/)
         return nil unless match
 

data/lib/rubyn_code/db/schema.rb

@@ -15,9 +15,9 @@ module RubynCode
       # @return [Integer, nil] the version number, or nil if no migrations applied
       def current_version
         row = @connection.query(
-          "SELECT MAX(version) AS max_version FROM schema_migrations"
+          'SELECT MAX(version) AS max_version FROM schema_migrations'
         ).to_a.first
-        row && row["max_version"]
+        row && row['max_version']
       rescue StandardError
         nil
       end
@@ -27,8 +27,8 @@ module RubynCode
       # @return [Array<Integer>]
       def applied_versions
         @connection.query(
-          "SELECT version FROM schema_migrations ORDER BY version"
-        ).to_a.map { |row| row["version"] }
+          'SELECT version FROM schema_migrations ORDER BY version'
+        ).to_a.map { |row| row['version'] }
       rescue StandardError
         []
       end
@@ -39,7 +39,7 @@ module RubynCode
       # @return [Boolean]
       def version_applied?(version)
         rows = @connection.query(
-          "SELECT 1 FROM schema_migrations WHERE version = ?", [version]
+          'SELECT 1 FROM schema_migrations WHERE version = ?', [version]
         ).to_a
         !rows.empty?
       rescue StandardError
@@ -53,7 +53,7 @@ module RubynCode
         @connection.query(
           "SELECT name FROM sqlite_master WHERE type = 'table' " \
           "AND name NOT LIKE 'sqlite_%' ORDER BY name"
-        ).to_a.map { |row| row["name"] }
+        ).to_a.map { |row| row['name'] }
       end
 
       # Returns column information for the given table.

data/lib/rubyn_code/debug.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'pastel'
+
+module RubynCode
+  module Debug
+    PASTEL = Pastel.new
+
+    @enabled = false
+    @output = $stderr
+
+    class << self
+      attr_reader :enabled
+
+      def enable!
+        @enabled = true
+      end
+
+      def disable!
+        @enabled = false
+      end
+
+      def enabled?
+        @enabled || ENV.fetch('RUBYN_DEBUG', nil)
+      end
+
+      attr_writer :output
+
+      # ── Core logging ──────────────────────────────────────────────
+
+      def log(tag, message, color: :dim)
+        return unless enabled?
+
+        timestamp = Time.now.strftime('%H:%M:%S.%L')
+        prefix = "#{PASTEL.dim("[#{timestamp}]")} #{PASTEL.send(color, "[#{tag}]")}"
+        @output.puts "#{prefix} #{message}"
+      end
+
+      # ── Convenience methods ───────────────────────────────────────
+
+      def llm(message)
+        log('llm', message, color: :magenta)
+      end
+
+      def tool(message)
+        log('tool', message, color: :cyan)
+      end
+
+      def agent(message)
+        log('agent', message, color: :yellow)
+      end
+
+      def loop_tick(message)
+        log('loop', message, color: :green)
+      end
+
+      def recovery(message)
+        log('recovery', message, color: :red)
+      end
+
+      def token(message)
+        log('token', message, color: :blue)
+      end
+
+      def warn(message)
+        log('warn', message, color: :yellow)
+      end
+
+      def error(message)
+        log('error', message, color: :red)
+      end
+    end
+  end
+end

data/lib/rubyn_code/hooks/RUBYN.md

@@ -0,0 +1,17 @@
+# Layer 14: Hooks
+
+Event hooks for extending agent behavior.
+
+## Classes
+
+- **`Registry`** — Stores hook definitions keyed by event name. Events include
+  `before_tool`, `after_tool`, `before_llm`, `after_llm`, `on_error`, etc.
+
+- **`Runner`** — Executes registered hooks when events fire. Hooks run synchronously
+  in registration order. A hook can modify or abort the event.
+
+- **`BuiltIn`** — Default hooks shipped with the gem: logging, cost tracking,
+  context auto-compaction triggers.
+
+- **`UserHooks`** — Loads user-defined hooks from `~/.rubyn-code/hooks/` or
+  project-level `.rubyn-code/hooks/`. Ruby files that register via the `Registry`.

data/lib/rubyn_code/hooks/built_in.rb

@@ -22,14 +22,14 @@ module RubynCode
         def call(response:, **_kwargs)
           return unless @budget_enforcer
 
-          usage = response[:usage] || response["usage"]
+          usage = response[:usage] || response['usage']
           return unless usage
 
-          model          = response[:model] || response["model"] || "unknown"
-          input_tokens   = usage[:input_tokens] || usage["input_tokens"] || 0
-          output_tokens  = usage[:output_tokens] || usage["output_tokens"] || 0
-          cache_read     = usage[:cache_read_input_tokens] || usage["cache_read_input_tokens"] || 0
-          cache_write    = usage[:cache_creation_input_tokens] || usage["cache_creation_input_tokens"] || 0
+          model          = response[:model] || response['model'] || 'unknown'
+          input_tokens   = usage[:input_tokens] || usage['input_tokens'] || 0
+          output_tokens  = usage[:output_tokens] || usage['output_tokens'] || 0
+          cache_read     = usage[:cache_read_input_tokens] || usage['cache_read_input_tokens'] || 0
+          cache_write    = usage[:cache_creation_input_tokens] || usage['cache_creation_input_tokens'] || 0
 
           @budget_enforcer.record!(
             model: model,
@@ -114,9 +114,9 @@ module RubynCode
             registry.on(:post_tool_use, logging_hook, priority: 50)
           end
 
-          if context_manager
-            registry.on(:post_llm_call, AutoCompactHook.new(context_manager: context_manager), priority: 90)
-          end
+          return unless context_manager
+
+          registry.on(:post_llm_call, AutoCompactHook.new(context_manager: context_manager), priority: 90)
         end
       end
     end

data/lib/rubyn_code/hooks/registry.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "monitor"
+require 'monitor'
 
 module RubynCode
   module Hooks
@@ -24,7 +24,7 @@ module RubynCode
       include MonitorMixin
 
       def initialize
-        super() # MonitorMixin
+        super # MonitorMixin
         @hooks = {}
         VALID_EVENTS.each { |event| @hooks[event] = [] }
       end
@@ -41,8 +41,8 @@ module RubynCode
         validate_event!(event)
 
         handler = callable || block
-        raise ArgumentError, "A callable or block is required" unless handler
-        raise ArgumentError, "Hook must respond to #call" unless handler.respond_to?(:call)
+        raise ArgumentError, 'A callable or block is required' unless handler
+        raise ArgumentError, 'Hook must respond to #call' unless handler.respond_to?(:call)
 
         synchronize do
           @hooks[event] << Hook.new(callable: handler, priority: priority)
@@ -92,7 +92,7 @@ module RubynCode
         return if VALID_EVENTS.include?(event)
 
         raise ArgumentError,
-              "Unknown event #{event.inspect}. Valid events: #{VALID_EVENTS.join(", ")}"
+              "Unknown event #{event.inspect}. Valid events: #{VALID_EVENTS.join(', ')}"
       end
     end
   end

data/lib/rubyn_code/hooks/runner.rb

@@ -45,7 +45,7 @@ module RubynCode
           result = safe_call(hook, :pre_tool_use, context)
           next unless result.is_a?(Hash) && result[:deny]
 
-          return { deny: true, reason: result[:reason] || "Denied by hook" }
+          return { deny: true, reason: result[:reason] || 'Denied by hook' }
         end
 
         nil