rubik 0.1.0

data/lib/rubik/tools/builtins/symbols.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+require_relative "../../coeffects"
+require_relative "../output"
+require_relative "../diagnostic_reporter"
+require_relative "../fuzzy_matcher"
+
+module Rubik
+  module Tools
+    class SearchSymbolsTool < BaseTool
+      # Declared coeffects: hidden from schemas (PENDING) until satisfied (AGENTS.md §2).
+      REQUIRES = [Rubik::Coeffects::AST_GRAPH].freeze
+
+      DECLARATION = Declaration.new(
+        name: "search_symbols", aliases: ["find_symbols", "symbols"],
+        description: "Search function, class, struct definitions and call hierarchies in the AST symbol graph",
+        risk: :read, archetypes: [:research],
+        params_schema: {
+          type: "object",
+          properties: {
+            query: { type: "string", description: "Symbol name or partial name to search" },
+            smart_context: { type: "boolean", description: "Return full smart context with dependencies (optional)" }
+          },
+          required: ["query"]
+        }
+      )
+      def initialize(ast_graph = nil, runtime_context: nil, context: nil)
+        super(DECLARATION)
+        @ast_graph = ast_graph
+        @runtime_context = runtime_context || context
+      end
+
+      def ast_graph
+        Rubik::Coeffects.resolve(@runtime_context, Rubik::Coeffects::AST_GRAPH, @ast_graph)
+      end
+
+      def execute(args = {})
+        query = (args["query"] || args[:query]).to_s.strip
+        return ToolOutput.error("Query parameter is required.") if query.empty?
+
+        graph = ast_graph
+        return ToolOutput.error("AST graph is not available. Run '!context scan' to build the symbol index.") unless graph
+
+        if args["smart_context"] || args[:smart_context]
+          ctx = graph.smart_context_for(query)
+          return ctx.empty? ? "No smart context found for '#{query}'." : ctx
+        end
+
+        matches = if graph.respond_to?(:search_symbols)
+                    graph.search_symbols(query)
+                  else
+                    graph.symbols.values.select { |sym| sym.name.downcase.include?(query.downcase) }
+                  end
+
+        if matches.empty?
+          all_sym_names = graph.respond_to?(:symbols) ? graph.symbols.keys : []
+          candidates = FuzzyMatcher.best_matches(query, all_sym_names)
+          DiagnosticReporter.render_symbol_not_found(query, candidate_symbols: candidates)
+        else
+          matches.map do |sym|
+            "• #{sym.kind.to_s.upcase} #{sym.name} (#{sym.file}:#{sym.line_start}-#{sym.line_end})\n  " \
+              "Signature: #{sym.signature}\n  Calls: #{sym.calls.join(', ')}"
+          end.join("\n\n")
+        end
+      end
+    end
+
+    class GetOutlineTool < BaseTool
+      # Declared coeffects: hidden from schemas (PENDING) until satisfied (AGENTS.md §2).
+      REQUIRES = [Rubik::Coeffects::AST_GRAPH].freeze
+
+      DECLARATION = Declaration.new(
+        name: "get_outline", aliases: ["file_outline", "outline"],
+        description: "Get high-level semantic outline (classes, methods, functions, and line ranges) " \
+                     "of a source file from the AST without reading entire file content. " \
+                     "Accepts 'file_path' (or 'path').",
+        risk: :read, archetypes: [:research],
+        params_schema: {
+          type: "object",
+          properties: {
+            file_path: { type: "string", description: "Path to source file to inspect" }
+          },
+          required: ["file_path"]
+        }
+      )
+      def initialize(ast_graph = nil, runtime_context: nil, context: nil)
+        super(DECLARATION)
+        @ast_graph = ast_graph
+        @runtime_context = runtime_context || context
+      end
+
+      def ast_graph
+        Rubik::Coeffects.resolve(@runtime_context, Rubik::Coeffects::AST_GRAPH, @ast_graph)
+      end
+
+      def execute(args = {})
+        path = (args["file_path"] || args[:file_path] || args["path"] || args[:path]).to_s.strip
+        return ToolOutput.error("File path is required.") if path.empty?
+
+        graph = ast_graph
+        return ToolOutput.error("AST graph is not available. Run '!context scan' to build the symbol index.") unless graph
+
+        graph.outline_for(path)
+      end
+    end
+
+    class FindReferencesTool < BaseTool
+      # Declared coeffects: hidden from schemas (PENDING) until satisfied (AGENTS.md §2).
+      REQUIRES = [Rubik::Coeffects::AST_GRAPH].freeze
+
+      DECLARATION = Declaration.new(
+        name: "find_references", aliases: ["references", "get_callers"],
+        description: "Find all call sites, callers, and references of a symbol/function/class across the workspace for safe refactoring. " \
+                     "This is based on the AST symbol graph; for a catch-all text search matching names, use grep_search. " \
+                     "Accepts 'symbol_name' (or 'symbol').",
+        risk: :read, archetypes: [:research],
+        params_schema: {
+          type: "object",
+          properties: {
+            symbol_name: { type: "string", description: "Symbol name to find callers/references for" }
+          },
+          required: ["symbol_name"]
+        }
+      )
+      def initialize(ast_graph = nil, runtime_context: nil, context: nil)
+        super(DECLARATION)
+        @ast_graph = ast_graph
+        @runtime_context = runtime_context || context
+      end
+
+      def ast_graph
+        Rubik::Coeffects.resolve(@runtime_context, Rubik::Coeffects::AST_GRAPH, @ast_graph)
+      end
+
+      def execute(args = {})
+        sym_name = (args["symbol_name"] || args[:symbol_name] || args["symbol"] || args[:symbol]).to_s.strip
+        return ToolOutput.error("Symbol name is required.") if sym_name.empty?
+
+        graph = ast_graph
+        return ToolOutput.error("AST graph is not available. Run '!context scan' to build the symbol index.") unless graph
+
+        callers = graph.callers_of(sym_name)
+        if callers.empty?
+          "No references or callers found for '#{sym_name}' in AST graph."
+        else
+          lines = ["Found #{callers.size} reference(s) for '#{sym_name}':"]
+          callers.each do |c|
+            lines << "  • #{c.name} (#{c.file}:#{c.line_start}-#{c.line_end}) -> #{c.signature}"
+          end
+          lines.join("\n")
+        end
+      end
+    end
+
+    class GetSymbolTool < BaseTool
+      # Declared coeffects: hidden from schemas (PENDING) until satisfied (AGENTS.md §2).
+      REQUIRES = [Rubik::Coeffects::AST_GRAPH].freeze
+
+      DECLARATION = Declaration.new(
+        name: "get_symbol", aliases: ["get_definition", "symbol_info"],
+        description: "Get isolated definition, signature, docstring, and body of a specific class or method from the AST. " \
+                     "Accepts 'symbol_name' (or 'symbol').",
+        risk: :read, archetypes: [:research],
+        params_schema: {
+          type: "object",
+          properties: {
+            symbol_name: { type: "string", description: "Symbol name to retrieve definition for" }
+          },
+          required: ["symbol_name"]
+        }
+      )
+      def initialize(ast_graph = nil, runtime_context: nil, context: nil)
+        super(DECLARATION)
+        @ast_graph = ast_graph
+        @runtime_context = runtime_context || context
+      end
+
+      def ast_graph
+        Rubik::Coeffects.resolve(@runtime_context, Rubik::Coeffects::AST_GRAPH, @ast_graph)
+      end
+
+      def execute(args = {})
+        sym_name = (args["symbol_name"] || args[:symbol_name] || args["symbol"] || args[:symbol]).to_s.strip
+        return ToolOutput.error("Symbol name is required.") if sym_name.empty?
+
+        graph = ast_graph
+        return ToolOutput.error("AST graph is not available. Run '!context scan' to build the symbol index.") unless graph
+
+        info = graph.symbol_definition(sym_name)
+        unless info
+          all_sym_names = graph.respond_to?(:symbols) ? graph.symbols.keys : []
+          candidates = FuzzyMatcher.best_matches(sym_name, all_sym_names)
+          return ToolOutput.error(DiagnosticReporter.render_symbol_not_found(sym_name, candidate_symbols: candidates))
+        end
+
+        lines = [
+          "Symbol: #{info[:name]} [#{info[:kind].to_s.upcase}]",
+          "File: #{info[:file]} (lines #{info[:line_start]}-#{info[:line_end]})",
+          "Signature: #{info[:signature]}"
+        ]
+        lines << "Docstring: #{info[:docstring]}" if info[:docstring] && !info[:docstring].empty?
+        lines << "Calls: #{info[:calls].join(', ')}" unless info[:calls].empty?
+        lines << "\n--- Body ---\n#{info[:body]}" if info[:body] && !info[:body].empty?
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/rubik/tools/builtins/synthesis.rb

@@ -0,0 +1,314 @@
+# frozen_string_literal: true
+
+require "stringio"
+require "timeout"
+require_relative "../base"
+require_relative "../output"
+require_relative "../preflight_runner"
+require_relative "../../runtime"
+
+module Rubik
+  module Tools
+    class SynthesizeCommandTool < BaseTool
+      DECLARATION = Declaration.new(
+        name: "synthesize_command", aliases: ["create_command", "add_command"],
+        description: "Dynamically create and register a new Rubik REPL bang command or tool at runtime (session, project, or global scope)",
+        risk: :write, maestro_blocked: false, # self-evolution plane (TOOLS.md maestro policy)
+        params_schema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Name of the new command without '!' (e.g. 'db_seed', 'benchmark_api')" },
+            description: { type: "string", description: "Short description of what the command does for !help" },
+            scope: { type: "string", enum: ["session", "project", "global"],
+                     description: "Storage scope: session (in-memory only), project (.rubik/commands), global (~/.rubik/commands)" },
+            code: { type: "string", description: "Ruby handler code: ->(args, ctx) { ... }. For 2-arity, ctx is the OUTPUT VIEW " \
+                                                 "(ctx.out / ctx.puts / ctx.print / ctx.flush). For config/services/full shell, " \
+                                                 "declare 3-arity ->(args, out, shell) instead." },
+            test_args: { type: "object", description: "Optional sample arguments to pre-flight verify the handler before registration (recommended)" }
+          },
+          required: ["name", "code"]
+        }
+      )
+      def initialize(shell = nil, overlay_storage = nil, guard = nil, legacy_runtime_manager = nil, runtime_manager: nil)
+        super(DECLARATION)
+        @shell = shell
+        # guard, fallback overlay storage'a da geçilir: bootstrap kabul taraması
+        # aynı operatör-policy guard örneğini kullanır (bkz. OverlayStorage).
+        @guard = guard || Rubik::Security::Guard.new
+        @overlay_storage = overlay_storage || Rubik::Runtime::OverlayStorage.new(guard: @guard)
+        @runtime_manager = runtime_manager || legacy_runtime_manager
+      end
+
+      def execute(args = {})
+        name = (args["name"] || args[:name]).to_s.strip.delete_prefix("!")
+        description = (args["description"] || args[:description] || "Custom dynamic command").to_s.strip
+        scope = (args["scope"] || args[:scope] || "session").to_s.downcase.to_sym
+        code = (args["code"] || args[:code]).to_s.strip
+        test_args = args["test_args"] || args[:test_args]
+
+        return ToolOutput.error("Command name cannot be empty") if name.empty?
+        return ToolOutput.error("Handler code cannot be empty") if code.empty?
+
+        clean_name = name.to_s.downcase.delete_prefix("!")
+        previous_meta = nil
+        if @shell
+          previous_meta = @shell.commands[clean_name]
+          return ToolOutput.error("Cannot overwrite reserved built-in command '!#{clean_name}'") if previous_meta && !previous_meta[:custom]
+        end
+
+        # 1. Security & Syntax Verification
+        begin
+          Rubik::Security::Guard.run_synthesis_gate(@guard, code)
+        rescue Rubik::Security::BlockedWriteError => e
+          return ToolOutput.error("Security blocked: #{e.message}")
+        rescue StandardError => e
+          return ToolOutput.error("Security blocked: Synthesized command code contains dangerous operations (#{e.message})")
+        end
+
+        proc_handler = begin
+          eval(code, clean_binding, __FILE__, __LINE__) # rubocop:disable Security/Eval -- sentez çekirdegi; @guard.verify_synthesis_safety! ön kosulu çalisir
+        rescue ScriptError, StandardError => e
+          return ToolOutput.error("Syntax error in synthesized code: #{e.message}") # rubocop:disable Lint/NoReturnInBeginEndBlocks -- araç hata akisinda bilinçli erken dönüş
+        end
+
+        unless proc_handler.respond_to?(:call)
+          return ToolOutput.error("Code must evaluate to a callable Proc or Lambda " \
+                                  "(e.g. ->(args, ctx) { ... } or ->(args, out, shell) { ... })")
+        end
+
+        # 1b. Optional pre-flight execution in an isolated child process
+        # (AGENTS.md §3.4): verifies the handler actually runs before it is
+        # persisted or registered. A subprocess guarantees the deadline even
+        # for C extensions and blocking syscalls that Timeout.timeout cannot
+        # preempt; output goes to a throwaway StringIO inside the child so
+        # verification never writes to the user's terminal.
+        if test_args
+          preflight = PreflightRunner.run(code, test_args, mode: :command, guard: @guard)
+          return ToolOutput.error("Pre-flight verification failed for command '!#{name}': #{preflight}") if preflight.is_a?(String)
+
+          if preflight == :spawn_failed
+            sub_ctx = @runtime_manager&.context.is_a?(Rubik::Runtime::Context) ? @runtime_manager.context.extend : nil
+            begin
+              failure = PreflightRunner.verify_in_process { PreflightRunner.call_handler(proc_handler, test_args, mode: :command, shell: @shell) }
+              return ToolOutput.error("Pre-flight verification failed for command '!#{name}': #{failure}") if failure
+            ensure
+              sub_ctx&.dispose
+            end
+          end
+        end
+
+        # 2. Persist to storage if scope is project or global
+        if [:project, :global].include?(scope)
+          save_res = @overlay_storage.save_command(name, code, scope: scope, description: description)
+          return ToolOutput.error("Failed to persist command: #{save_res[:error]}") unless save_res[:ok]
+        end
+
+        # 3. Register live in REPL shell
+        if @shell
+          @shell.register_command(name, description: "#{description} [#{scope}]", custom: true) do |cmd_args, ctx|
+            # Arity contract (mirrored by OverlayStorage#eval_command and
+            # PreflightRunner): 1 → args; 2 → the CommandContext (its
+            # puts/print/flush delegate to the active capture IO); 3 →
+            # (args, out, shell) for trusted code needing the raw shell.
+            # Direct invocation outside dispatch (tests, replay) has no
+            # ctx: use the shell's factory, or its raw output when held
+            # shell doubles predate the CommandContext contract. The warn
+            # keeps a dispatch site forgetting ctx visible instead of
+            # silently auto-healed.
+            out_ctx = if ctx
+                        ctx
+                      elsif @shell.respond_to?(:command_context)
+                        warn "[rubik] custom command invoked without a dispatch CommandContext" unless ENV["RUBIK_TEST"]
+                        @shell.command_context
+                      else
+                        @shell.output
+                      end
+            if proc_handler.arity == 1
+              proc_handler.call(cmd_args)
+            elsif proc_handler.arity == 2
+              proc_handler.call(cmd_args, out_ctx)
+            else
+              proc_handler.call(cmd_args, out_ctx.respond_to?(:out) ? out_ctx.out : out_ctx, @shell)
+            end
+          end
+
+          # Register inverse in Runtime Context. Sound rollback (AGENTS.md §1.A):
+          # a hot-updated custom command is restored to its previous handler on
+          # dispose instead of leaving a hole in the command table.
+          ctx = @runtime_manager&.context || (@shell.respond_to?(:runtime_manager) ? @shell.runtime_manager&.context : nil)
+          if ctx.respond_to?(:on_dispose) || ctx.respond_to?(:register_disposable)
+            hook = ctx.respond_to?(:on_dispose) ? :on_dispose : :register_disposable
+            ctx.send(hook) do
+              if previous_meta
+                @shell.register_command(clean_name, description: previous_meta[:description],
+                                                    custom: previous_meta[:custom], audience: previous_meta[:audience],
+                                        &previous_meta[:handler])
+              else
+                @shell.unregister_command(name)
+              end
+            end
+          end
+        end
+
+        "Successfully synthesized and registered !#{name} [scope: #{scope}]#{' (pre-flight verified)' if test_args}. " \
+          "You can now run it using !#{name} or via exec_repl_command('!#{name}')."
+      end
+
+      private
+
+      def clean_binding
+        Object.new.instance_eval { binding }
+      end
+    end
+
+    class SynthesizeToolTool < BaseTool
+      DECLARATION = Declaration.new(
+        name: "synthesize_tool", aliases: ["create_tool", "add_tool"],
+        description: "Synthesize, verify, and register a new native function calling tool into the agent's live toolbelt " \
+                     "at runtime (session, project, or global scope)",
+        risk: :write, maestro_blocked: false, # self-evolution plane (TOOLS.md maestro policy)
+        params_schema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Name of the new tool (e.g. 'calc_stats', 'inspect_ast_node')" },
+            description: { type: "string", description: "Clear explanation of what the tool does for model selection" },
+            scope: { type: "string", enum: ["session", "project", "global"],
+                     description: "Storage scope: session (in-memory only), project (.rubik/tools), global (~/.rubik/tools)" },
+            risk: { type: "string", enum: ["read", "write", "execute"], default: "execute",
+                    description: "Risk level of tool (optional; read/write/execute, default: execute)" },
+            params_schema: { type: "object", description: "JSON Schema definition of the tool parameters" },
+            code: { type: "string", description: "Ruby implementation of tool handler: ->(args) { ... } or class extending Rubik::Tools::BaseTool" },
+            test_args: { type: "object", description: "Optional test arguments to perform pre-flight verification in an isolated sandbox" }
+          },
+          required: ["name", "description", "code"]
+        }
+      )
+      def initialize(tool_registry = nil, overlay_storage = nil, guard = nil, legacy_runtime_manager = nil, runtime_manager: nil)
+        super(DECLARATION)
+        @tool_registry = tool_registry
+        # guard, fallback overlay storage'a da geçilir: bootstrap kabul taraması
+        # aynı operatör-policy guard örneğini kullanır (bkz. OverlayStorage).
+        @guard = guard || Rubik::Security::Guard.new
+        @overlay_storage = overlay_storage || Rubik::Runtime::OverlayStorage.new(guard: @guard)
+        @runtime_manager = runtime_manager || legacy_runtime_manager
+      end
+
+      def execute(args = {})
+        name = (args["name"] || args[:name]).to_s.strip.downcase.gsub(/[^a-z0-9_]/, "_")
+        description = (args["description"] || args[:description] || "Custom native tool").to_s.strip
+        scope = (args["scope"] || args[:scope] || "session").to_s.downcase.to_sym
+        risk = (args["risk"] || args[:risk] || "execute").to_s.downcase.to_sym
+        return ToolOutput.error("Invalid risk '#{risk}' — must be one of: read, write, execute.") unless [:read, :write, :execute].include?(risk)
+
+        schema = args["params_schema"] || args[:params_schema] || { type: "object", properties: {} }
+        code = (args["code"] || args[:code]).to_s.strip
+        test_args = args["test_args"] || args[:test_args]
+
+        return ToolOutput.error("Tool name cannot be empty") if name.empty?
+        return ToolOutput.error("Tool code cannot be empty") if code.empty?
+
+        # Guard against shadowing built-in tools. Registry#register silently
+        # overwrites, and the dispose inverse only unregisters — a synthesized
+        # "read_file" would leave the session without the real read_file after
+        # disposal. Built-ins are rejected here; overlay/MCP/synthesized tools
+        # may be hot-updated (previous instance is restored on dispose).
+        previous_tool = @tool_registry&.get(name)
+        if previous_tool && @tool_registry.origin(name) == :builtin
+          msg = "Cannot overwrite built-in tool '#{name}'. Choose a distinct name (e.g. 'my_#{name}')."
+          return ToolOutput.error(msg)
+        end
+
+        # 1. Security & Pre-flight Syntax Verification in isolated Context
+        begin
+          Rubik::Security::Guard.run_synthesis_gate(@guard, code)
+        rescue Rubik::Security::BlockedWriteError => e
+          return ToolOutput.error("Security blocked: #{e.message}")
+        rescue StandardError => e
+          return ToolOutput.error("Security blocked: Synthesized tool code contains dangerous operations (#{e.message})")
+        end
+
+        tool_instance = nil
+        begin
+          evaluated = eval(code, clean_binding, __FILE__, __LINE__) # rubocop:disable Security/Eval -- sentez çekirdegi
+          tool_instance = if evaluated.is_a?(Class) && evaluated < Rubik::Tools::BaseTool
+                            evaluated.new
+                          elsif evaluated.respond_to?(:call)
+                            Class.new(Rubik::Tools::BaseTool) do
+                              define_method(:initialize) do
+                                super(name: name, description: "#{description} [#{scope}]", risk: risk, params_schema: schema)
+                                @handler = evaluated
+                              end
+
+                              define_method(:execute) do |exec_args = {}|
+                                @handler.call(exec_args)
+                              end
+                            end.new
+                          else
+                            return ToolOutput.error("Tool code must evaluate to a callable Proc (->(args) { ... }) or a BaseTool subclass.")
+                          end
+
+          effective_test_args = test_args || {}
+          preflight = PreflightRunner.run(code, effective_test_args, mode: :tool, guard: @guard)
+          return ToolOutput.error("Pre-flight verification failed for tool '#{name}': #{preflight}") if preflight.is_a?(String)
+
+          if preflight == :spawn_failed
+            # Fallback: in-process Timeout (lambda form via the shared
+            # dispatch; BaseTool-subclass form needs the full runtime and
+            # always verifies in-process).
+            sub_ctx = @runtime_manager&.context.respond_to?(:extend) ? @runtime_manager.context.extend : nil
+            begin
+              failure = if evaluated.respond_to?(:call)
+                          PreflightRunner.verify_in_process { PreflightRunner.call_handler(evaluated, effective_test_args, mode: :tool) }
+                        else
+                          PreflightRunner.verify_in_process { tool_instance.execute(effective_test_args) }
+                        end
+              return ToolOutput.error("Pre-flight verification failed for tool '#{name}': #{failure}") if failure
+            ensure
+              sub_ctx&.dispose! if sub_ctx.respond_to?(:dispose!)
+            end
+          end
+        rescue ScriptError, StandardError => e
+          return ToolOutput.error("Pre-flight verification failed for tool '#{name}': #{e.message}")
+        end
+
+        # 2. Persist to storage if scope is project or global
+        if [:project, :global].include?(scope)
+          save_res = @overlay_storage.save_tool(name, code, scope: scope, description: description, params_schema: schema, risk: risk)
+          return ToolOutput.error("Failed to persist tool: #{save_res[:error]}") unless save_res[:ok]
+        end
+
+        # 3. Register live into active tool registry
+        if @tool_registry
+          previous_origin = previous_tool ? @tool_registry.origin(name) : nil
+          @tool_registry.register(tool_instance, origin: :synthesis)
+
+          # Register inverse in Runtime Context. When hot-updating an existing
+          # overlay/MCP/synthesized tool, the inverse restores the previous
+          # instance instead of leaving a hole in the toolbelt.
+          ctx = @runtime_manager&.context
+          ctx&.on_dispose do
+            if previous_tool && @tool_registry.respond_to?(:swap)
+              @tool_registry.swap(name, previous_tool, origin: previous_origin || :overlay)
+            else
+              @tool_registry.unregister(name)
+            end
+          end
+        end
+
+        verification_note = if test_args
+                              "Pre-flight verified with provided test_args in an isolated sub-context."
+                            else
+                              "Pre-flight verified with default arguments in an isolated sub-context."
+                            end
+        "🎉 Successfully synthesized and registered native tool '#{name}' [scope: #{scope}]. " \
+          "#{verification_note} It is now immediately available in your active toolbelt for function calling."
+      end
+
+      private
+
+      def clean_binding
+        Object.new.instance_eval { binding }
+      end
+    end
+  end
+end