rubyn-code 0.1.0

data/lib/rubyn_code/teams/manager.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require_relative "teammate"
+
+module RubynCode
+  module Teams
+    # CRUD manager for teammates backed by SQLite.
+    #
+    # Provides lifecycle management for agent teammates: spawning,
+    # listing, status updates, and removal.
+    class Manager
+      # @param db [DB::Connection] the database connection
+      # @param mailbox [Mailbox] the team mailbox for inter-agent messaging
+      def initialize(db, mailbox:)
+        @db = db
+        @mailbox = mailbox
+        ensure_table!
+      end
+
+      # Creates a new teammate record.
+      #
+      # @param name [String] unique teammate name
+      # @param role [String] the teammate's role description
+      # @param persona [String, nil] optional persona prompt
+      # @param model [String, nil] optional LLM model override
+      # @return [Teammate] the newly created teammate
+      # @raise [Error] if a teammate with the given name already exists
+      def spawn(name:, role:, persona: nil, model: nil)
+        existing = get(name)
+        raise Error, "Teammate '#{name}' already exists" if existing
+
+        id = SecureRandom.uuid
+        now = Time.now.utc.iso8601
+        metadata_json = JSON.generate({})
+
+        @db.execute(
+          <<~SQL,
+            INSERT INTO teammates (id, name, role, persona, model, status, metadata, created_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+          SQL
+          [id, name, role, persona, model, "idle", metadata_json, now]
+        )
+
+        Teammate.new(
+          id: id,
+          name: name,
+          role: role,
+          persona: persona,
+          model: model,
+          status: "idle",
+          metadata: {},
+          created_at: now
+        )
+      end
+
+      # Returns all teammates.
+      #
+      # @return [Array<Teammate>]
+      def list
+        rows = @db.query("SELECT * FROM teammates ORDER BY created_at ASC").to_a
+        rows.map { |row| row_to_teammate(row) }
+      end
+
+      # Finds a teammate by name.
+      #
+      # @param name [String]
+      # @return [Teammate, nil]
+      def get(name)
+        rows = @db.query("SELECT * FROM teammates WHERE name = ? LIMIT 1", [name]).to_a
+        return nil if rows.empty?
+
+        row_to_teammate(rows.first)
+      end
+
+      # Updates a teammate's status.
+      #
+      # @param name [String]
+      # @param status [String] one of "idle", "active", "offline"
+      # @return [void]
+      # @raise [ArgumentError] if the status is invalid
+      # @raise [Error] if the teammate is not found
+      def update_status(name, status)
+        unless VALID_STATUSES.include?(status)
+          raise ArgumentError, "Invalid status '#{status}'. Must be one of: #{VALID_STATUSES.join(', ')}"
+        end
+
+        teammate = get(name)
+        raise Error, "Teammate '#{name}' not found" unless teammate
+
+        @db.execute(
+          "UPDATE teammates SET status = ? WHERE name = ?",
+          [status, name]
+        )
+      end
+
+      # Removes a teammate by name.
+      #
+      # @param name [String]
+      # @return [void]
+      # @raise [Error] if the teammate is not found
+      def remove(name)
+        teammate = get(name)
+        raise Error, "Teammate '#{name}' not found" unless teammate
+
+        @db.execute("DELETE FROM teammates WHERE name = ?", [name])
+      end
+
+      # Returns all teammates with status "active".
+      #
+      # @return [Array<Teammate>]
+      def active_teammates
+        rows = @db.query(
+          "SELECT * FROM teammates WHERE status = ? ORDER BY created_at ASC",
+          ["active"]
+        ).to_a
+        rows.map { |row| row_to_teammate(row) }
+      end
+
+      private
+
+      # Converts a database row hash to a Teammate value object.
+      #
+      # @param row [Hash]
+      # @return [Teammate]
+      def row_to_teammate(row)
+        metadata = parse_metadata(row["metadata"])
+
+        Teammate.new(
+          id: row["id"],
+          name: row["name"],
+          role: row["role"],
+          persona: row["persona"],
+          model: row["model"],
+          status: row["status"],
+          metadata: metadata,
+          created_at: row["created_at"]
+        )
+      end
+
+      # Safely parses JSON metadata, returning an empty hash on failure.
+      #
+      # @param raw [String, nil]
+      # @return [Hash]
+      def parse_metadata(raw)
+        return {} if raw.nil? || raw.empty?
+
+        JSON.parse(raw, symbolize_names: true)
+      rescue JSON::ParserError
+        {}
+      end
+
+      # Creates the teammates table if it does not already exist.
+      def ensure_table!
+        @db.execute(<<~SQL)
+          CREATE TABLE IF NOT EXISTS teammates (
+            id TEXT PRIMARY KEY,
+            name TEXT NOT NULL UNIQUE,
+            role TEXT NOT NULL,
+            persona TEXT,
+            model TEXT,
+            status TEXT NOT NULL DEFAULT 'idle',
+            metadata TEXT NOT NULL DEFAULT '{}',
+            created_at TEXT NOT NULL
+          )
+        SQL
+
+        @db.execute(<<~SQL)
+          CREATE UNIQUE INDEX IF NOT EXISTS idx_teammates_name ON teammates (name)
+        SQL
+      end
+    end
+  end
+end

data/lib/rubyn_code/teams/teammate.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module Teams
+    # Immutable value object representing a teammate in an agent team.
+    #
+    # Status values: "idle", "active", "offline"
+    VALID_STATUSES = %w[idle active offline].freeze
+
+    Teammate = Data.define(
+      :id, :name, :role, :persona, :model, :status, :metadata, :created_at
+    ) do
+
+      # @return [Boolean]
+      def idle? = status == "idle"
+
+      # @return [Boolean]
+      def active? = status == "active"
+
+      # @return [Boolean]
+      def offline? = status == "offline"
+
+      # @return [Hash]
+      def to_h
+        {
+          id: id,
+          name: name,
+          role: role,
+          persona: persona,
+          model: model,
+          status: status,
+          metadata: metadata,
+          created_at: created_at
+        }
+      end
+    end
+  end
+end

data/lib/rubyn_code/tools/background_run.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "registry"
+
+module RubynCode
+  module Tools
+    class BackgroundRun < Base
+      TOOL_NAME = "background_run"
+      DESCRIPTION = "Run a command in the background (test suites, builds, deploys). " \
+                    "Returns immediately with a job ID. Results are delivered automatically " \
+                    "before your next LLM call."
+      PARAMETERS = {
+        command: {
+          type: :string,
+          description: "The shell command to run in the background",
+          required: true
+        },
+        timeout: {
+          type: :integer,
+          description: "Timeout in seconds (default: 300)",
+          required: false
+        }
+      }.freeze
+      RISK_LEVEL = :execute
+
+      attr_writer :background_worker
+
+      def execute(command:, timeout: 300)
+        unless @background_worker
+          return "Error: Background worker not available. Use bash tool instead."
+        end
+
+        job_id = @background_worker.run(command, timeout: timeout)
+        "Background job started: #{job_id}\nCommand: #{command}\nTimeout: #{timeout}s\nResults will appear automatically when complete."
+      end
+    end
+
+    Registry.register(BackgroundRun)
+  end
+end

data/lib/rubyn_code/tools/base.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module Tools
+    class Base
+      TOOL_NAME = ""
+      DESCRIPTION = ""
+      PARAMETERS = {}.freeze
+      RISK_LEVEL = :read
+      REQUIRES_CONFIRMATION = false
+
+      class << self
+        def tool_name
+          const_get(:TOOL_NAME)
+        end
+
+        def description
+          const_get(:DESCRIPTION)
+        end
+
+        def parameters
+          const_get(:PARAMETERS)
+        end
+
+        def risk_level
+          const_get(:RISK_LEVEL)
+        end
+
+        def requires_confirmation?
+          const_get(:REQUIRES_CONFIRMATION)
+        end
+
+        def to_schema
+          {
+            name: tool_name,
+            description: description,
+            input_schema: Schema.build(parameters)
+          }
+        end
+      end
+
+      attr_reader :project_root
+
+      def initialize(project_root:)
+        @project_root = File.expand_path(project_root)
+      end
+
+      def execute(**params)
+        raise NotImplementedError, "#{self.class}#execute must be implemented"
+      end
+
+      def safe_path(path)
+        expanded = if Pathname.new(path).absolute?
+                     File.expand_path(path)
+                   else
+                     File.expand_path(path, project_root)
+                   end
+
+        unless expanded.start_with?(project_root)
+          raise PermissionDeniedError, "Path traversal denied: #{path} resolves outside project root"
+        end
+
+        expanded
+      end
+
+      def truncate(output, max: 50_000)
+        return output if output.nil? || output.length <= max
+
+        half = max / 2
+        "#{output[0, half]}\n\n... [truncated #{output.length - max} characters] ...\n\n#{output[-half, half]}"
+      end
+
+      private
+
+      def read_file_safely(path)
+        resolved = safe_path(path)
+        raise Error, "File not found: #{path}" unless File.exist?(resolved)
+        raise Error, "Not a file: #{path}" unless File.file?(resolved)
+
+        resolved
+      end
+    end
+  end
+end

data/lib/rubyn_code/tools/bash.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "open3"
+require "timeout"
+require_relative "base"
+require_relative "registry"
+
+module RubynCode
+  module Tools
+    class Bash < Base
+      TOOL_NAME = "bash"
+      DESCRIPTION = "Runs a shell command in the project directory. Blocks dangerous patterns and scrubs sensitive environment variables."
+      PARAMETERS = {
+        command: { type: :string, required: true, description: "The shell command to execute" },
+        timeout: { type: :integer, required: false, default: 120, description: "Timeout in seconds (default: 120)" }
+      }.freeze
+      RISK_LEVEL = :execute
+      REQUIRES_CONFIRMATION = true
+
+      def execute(command:, timeout: 120)
+        validate_command!(command)
+
+        env = scrubbed_env
+
+        stdout, stderr, status = nil
+        begin
+          Timeout.timeout(timeout) do
+            stdout, stderr, status = Open3.capture3(env, command, chdir: project_root)
+          end
+        rescue Timeout::Error
+          raise Error, "Command timed out after #{timeout} seconds: #{command}"
+        end
+
+        output = build_output(stdout, stderr, status)
+        output
+      end
+
+      private
+
+      def validate_command!(command)
+        Config::Defaults::DANGEROUS_PATTERNS.each do |pattern|
+          if command.include?(pattern)
+            raise PermissionDeniedError, "Blocked dangerous command pattern: '#{pattern}'"
+          end
+        end
+      end
+
+      def scrubbed_env
+        env = ENV.to_h.dup
+
+        env.each_key do |key|
+          if Config::Defaults::SCRUB_ENV_VARS.any? { |sensitive| key.upcase.include?(sensitive) }
+            env[key] = "[SCRUBBED]"
+          end
+        end
+
+        env
+      end
+
+      def build_output(stdout, stderr, status)
+        parts = []
+
+        unless stdout.empty?
+          parts << stdout
+        end
+
+        unless stderr.empty?
+          parts << "STDERR:\n#{stderr}"
+        end
+
+        unless status.success?
+          parts << "Exit code: #{status.exitstatus}"
+        end
+
+        parts.empty? ? "(no output)" : parts.join("\n")
+      end
+    end
+
+    Registry.register(Bash)
+  end
+end

data/lib/rubyn_code/tools/bundle_add.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "base"
+require_relative "registry"
+
+module RubynCode
+  module Tools
+    class BundleAdd < Base
+      TOOL_NAME = "bundle_add"
+      DESCRIPTION = "Adds a gem to the Gemfile and installs it via `bundle add`."
+      PARAMETERS = {
+        gem_name: { type: :string, required: true, description: "Name of the gem to add" },
+        version: { type: :string, required: false, description: "Version constraint (e.g. '~> 1.0')" },
+        group: { type: :string, required: false, description: "Gemfile group (e.g. 'development', 'test')" }
+      }.freeze
+      RISK_LEVEL = :execute
+      REQUIRES_CONFIRMATION = false
+
+      def execute(gem_name:, version: nil, group: nil)
+        gemfile_path = File.join(project_root, "Gemfile")
+
+        unless File.exist?(gemfile_path)
+          raise Error, "No Gemfile found in project root. Cannot run bundle add."
+        end
+
+        command = build_command(gem_name, version, group)
+        stdout, stderr, status = Open3.capture3(command, chdir: project_root)
+
+        build_output(stdout, stderr, status)
+      end
+
+      private
+
+      def build_command(gem_name, version, group)
+        cmd = "bundle add #{gem_name}"
+        cmd += " --version '#{version}'" if version
+        cmd += " --group #{group}" if group
+        cmd
+      end
+
+      def build_output(stdout, stderr, status)
+        parts = []
+        parts << stdout unless stdout.empty?
+        parts << "STDERR:\n#{stderr}" unless stderr.empty?
+        parts << "Exit code: #{status.exitstatus}" unless status.success?
+        parts.empty? ? "(no output)" : parts.join("\n")
+      end
+    end
+
+    Registry.register(BundleAdd)
+  end
+end

data/lib/rubyn_code/tools/bundle_install.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "base"
+require_relative "registry"
+
+module RubynCode
+  module Tools
+    class BundleInstall < Base
+      TOOL_NAME = "bundle_install"
+      DESCRIPTION = "Runs `bundle install` to install gem dependencies."
+      PARAMETERS = {}.freeze
+      RISK_LEVEL = :execute
+      REQUIRES_CONFIRMATION = false
+
+      def execute(**_params)
+        gemfile_path = File.join(project_root, "Gemfile")
+
+        unless File.exist?(gemfile_path)
+          raise Error, "No Gemfile found in project root. Cannot run bundle install."
+        end
+
+        stdout, stderr, status = Open3.capture3("bundle install", chdir: project_root)
+
+        build_output(stdout, stderr, status)
+      end
+
+      private
+
+      def build_output(stdout, stderr, status)
+        parts = []
+        parts << stdout unless stdout.empty?
+        parts << "STDERR:\n#{stderr}" unless stderr.empty?
+        parts << "Exit code: #{status.exitstatus}" unless status.success?
+        parts.empty? ? "(no output)" : parts.join("\n")
+      end
+    end
+
+    Registry.register(BundleInstall)
+  end
+end

data/lib/rubyn_code/tools/compact.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "registry"
+
+module RubynCode
+  module Tools
+    class Compact < Base
+      TOOL_NAME = "compact"
+      DESCRIPTION = "Triggers manual context compaction to reduce conversation size while preserving key information."
+      PARAMETERS = {
+        focus: { type: :string, required: false, description: "What to focus the summary on (e.g. 'the auth refactor', 'test failures')" }
+      }.freeze
+      RISK_LEVEL = :read
+      REQUIRES_CONFIRMATION = false
+
+      def initialize(project_root:, context_manager: nil)
+        super(project_root: project_root)
+        @context_manager = context_manager
+      end
+
+      def execute(focus: nil)
+        manager = @context_manager
+
+        unless manager
+          return "Context compaction is not available in this session. " \
+                 "No context manager was provided."
+        end
+
+        if manager.respond_to?(:compact)
+          result = manager.compact(focus: focus)
+          format_result(result, focus)
+        else
+          "Context manager does not support compaction."
+        end
+      end
+
+      private
+
+      def format_result(result, focus)
+        parts = ["Context compacted successfully."]
+
+        if result.is_a?(Hash)
+          parts << "Messages before: #{result[:before]}" if result[:before]
+          parts << "Messages after: #{result[:after]}" if result[:after]
+          parts << "Tokens saved: ~#{result[:tokens_saved]}" if result[:tokens_saved]
+        end
+
+        parts << "Focus: #{focus}" if focus
+
+        parts.join("\n")
+      end
+    end
+
+    Registry.register(Compact)
+  end
+end

data/lib/rubyn_code/tools/db_migrate.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "base"
+require_relative "registry"
+
+module RubynCode
+  module Tools
+    class DbMigrate < Base
+      TOOL_NAME = "db_migrate"
+      DESCRIPTION = "Runs Rails database migrations (up) or rollback (down)."
+      PARAMETERS = {
+        direction: { type: :string, required: false, default: "up", enum: %w[up down], description: "Migration direction: 'up' to migrate, 'down' to rollback (default: 'up')" },
+        steps: { type: :integer, required: false, description: "Number of steps to rollback (only used with direction 'down')" }
+      }.freeze
+      RISK_LEVEL = :execute
+      REQUIRES_CONFIRMATION = false
+
+      def execute(direction: "up", steps: nil)
+        command = build_command(direction, steps)
+        stdout, stderr, status = Open3.capture3(command, chdir: project_root)
+
+        build_output(stdout, stderr, status)
+      end
+
+      private
+
+      def build_command(direction, steps)
+        case direction
+        when "up"
+          "bundle exec rails db:migrate"
+        when "down"
+          cmd = "bundle exec rails db:rollback"
+          cmd += " STEP=#{steps.to_i}" if steps && steps.to_i > 0
+          cmd
+        else
+          raise Error, "Invalid direction: #{direction}. Must be 'up' or 'down'."
+        end
+      end
+
+      def build_output(stdout, stderr, status)
+        parts = []
+        parts << stdout unless stdout.empty?
+        parts << "STDERR:\n#{stderr}" unless stderr.empty?
+        parts << "Exit code: #{status.exitstatus}" unless status.success?
+        parts.empty? ? "(no output)" : parts.join("\n")
+      end
+    end
+
+    Registry.register(DbMigrate)
+  end
+end

data/lib/rubyn_code/tools/edit_file.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "registry"
+
+module RubynCode
+  module Tools
+    class EditFile < Base
+      TOOL_NAME = "edit_file"
+      DESCRIPTION = "Performs exact string replacement in a file. Fails if old_text is not found or is ambiguous."
+      PARAMETERS = {
+        path: { type: :string, required: true, description: "Path to the file to edit" },
+        old_text: { type: :string, required: true, description: "The exact text to find and replace" },
+        new_text: { type: :string, required: true, description: "The replacement text" },
+        replace_all: { type: :boolean, required: false, default: false, description: "Replace all occurrences (default: false)" }
+      }.freeze
+      RISK_LEVEL = :write
+      REQUIRES_CONFIRMATION = false
+
+      def execute(path:, old_text:, new_text:, replace_all: false)
+        resolved = read_file_safely(path)
+        content = File.read(resolved)
+
+        occurrences = content.scan(old_text).length
+
+        if occurrences.zero?
+          raise Error, "old_text not found in #{path}. No changes made."
+        end
+
+        if !replace_all && occurrences > 1
+          raise Error, "old_text found #{occurrences} times in #{path}. Use replace_all: true to replace all, or provide a more specific old_text."
+        end
+
+        new_content = if replace_all
+                        content.gsub(old_text, new_text)
+                      else
+                        content.sub(old_text, new_text)
+                      end
+
+        File.write(resolved, new_content)
+
+        replaced_count = replace_all ? occurrences : 1
+        "Successfully replaced #{replaced_count} occurrence#{'s' if replaced_count > 1} in #{path}"
+      end
+    end
+
+    Registry.register(EditFile)
+  end
+end