parse-stack-next 4.5.0

data/Rakefile

@@ -0,0 +1,573 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require "yard"
+require "rake/testtask"
+
+# Several MCP/debug tasks need to run `Parse.setup(...)` against a
+# local Parse instance. This helper preserves the local-stack
+# convenience defaults while refusing to apply those defaults against
+# anything that isn't a loopback URL — so a developer who pointed
+# `PARSE_SERVER_URL` at a real Parse Server but forgot to set the
+# secret env vars gets a loud abort instead of a silent boot with
+# placeholder credentials.
+#
+# @return [Array(String, String, String, String)]
+#   server_url, application_id, api_key, master_key
+def mcp_credentials_or_abort!
+  server_url   = ENV["PARSE_SERVER_URL"] || "http://localhost:2337/parse"
+  app_id       = ENV["PARSE_APP_ID"]
+  rest_api_key = ENV["PARSE_API_KEY"]
+  master_key   = ENV["PARSE_MASTER_KEY"]
+
+  is_local = server_url =~ %r{\Ahttps?://(?:localhost|127\.0\.0\.1|::1|\[::1\])(?::|/|\z)}
+
+  if app_id.to_s.empty? || master_key.to_s.empty?
+    if is_local
+      app_id       = (app_id.to_s.empty? ? "myAppId" : app_id)
+      rest_api_key = (rest_api_key.to_s.empty? ? "myApiKey" : rest_api_key)
+      master_key   = (master_key.to_s.empty? ? "myMasterKey" : master_key)
+    else
+      abort "[Rakefile] PARSE_SERVER_URL=#{server_url} is not local; refusing to fall back to " \
+            "placeholder credentials. Set PARSE_APP_ID and PARSE_MASTER_KEY explicitly."
+    end
+  end
+
+  [server_url, app_id, rest_api_key, master_key]
+end
+
+# Default test task runs all tests with Docker enabled
+Rake::TestTask.new do |t|
+  ENV['PARSE_TEST_USE_DOCKER'] = 'true'
+  t.libs << "lib/parse/stack"
+  t.test_files = FileList["test/lib/**/*_test.rb"]
+  t.warning = false
+  t.verbose = true
+end
+
+# Integration tests require Docker
+namespace :test do
+  desc "Run all integration tests (requires Docker)"
+  task :integration do
+    integration_files = FileList["test/lib/**/*integration_test.rb"]
+    
+    puts "Running #{integration_files.length} integration test files..."
+    integration_files.each_with_index do |file, index|
+      puts "Running integration test #{index + 1}/#{integration_files.length}: #{file}"
+
+      # 10: docker integration test fails for cloud functions
+      skip_till = 0
+      if (index + 1) <= skip_till
+        puts "Skipping test #{index + 1} as per configuration\n"
+        next
+      end
+
+      puts "\n" + "="*80
+      puts "Running: #{file}"
+      puts "="*80
+      system("PARSE_TEST_USE_DOCKER=true ruby -Ilib:test #{file}") || exit(1)
+    end
+    puts "\n✅ All integration tests completed successfully!"
+  end
+
+  desc "Run unit tests only (no Docker required)"
+  task :unit do
+    unit_files = FileList["test/lib/**/*_test.rb"].exclude("test/lib/**/*integration_test.rb")
+    
+    puts "Running #{unit_files.length} unit test files (no Docker)..."
+    unit_files.each_with_index do |file, index|
+      puts "Running unit test #{index + 1}/#{unit_files.length}: #{file}"
+
+      # 73 is problematic Testing Contains and Nin with Parse Objects with contains and nin 
+      skip_till = 0
+      if (index + 1) <= skip_till
+        puts "Skipping test #{index + 1} as per configuration"
+        next
+      end
+
+      system("PARSE_TEST_USE_DOCKER=true ruby -Ilib:test #{file}") || exit(1)
+    end
+    puts "\n✅ All unit tests completed successfully!"
+  end
+
+  desc "List all available test files"
+  task :list do
+    puts "\nIntegration Tests:"
+    FileList["test/lib/**/*integration_test.rb"].each { |f| puts "  #{f}" }
+
+    puts "\nUnit Tests:"
+    FileList["test/lib/**/*_test.rb"].exclude("test/lib/**/*integration_test.rb").each { |f| puts "  #{f}" }
+  end
+
+  # ---------------------------------------------------------------------------
+  # MCP protocol conformance via Anthropic's official mcp-inspector tool.
+  #
+  # Boots a local MCPServer against a configured Parse Server, then runs
+  # @modelcontextprotocol/inspector in CLI mode to validate the MCP wire
+  # protocol (initialize handshake, tools/list, tools/call, prompts/list,
+  # resources/list, error envelopes). Catches protocol regressions that
+  # in-process integration tests can miss because they exercise the Ruby
+  # call surface, not the JSON wire format an external MCP client sees.
+  #
+  # Requirements:
+  #   - npx on PATH (Node.js 18+)
+  #   - A running Parse Server (e.g., `docker-compose -f scripts/docker/
+  #     docker-compose.test.yml up -d`)
+  #   - Env: PARSE_SERVER_URL, PARSE_APP_ID, PARSE_API_KEY (defaults match
+  #     the Docker compose setup in scripts/docker/docker-compose.test.yml)
+  #
+  # Usage:
+  #   rake test:mcp_inspector
+  #   rake test:mcp_inspector METHOD=tools/list  # override target method
+  # ---------------------------------------------------------------------------
+  desc "Validate MCP protocol with Anthropic's mcp-inspector (requires npx)"
+  task :mcp_inspector do
+    require "net/http"
+    require "uri"
+    require "fileutils"
+
+    unless system("which npx > /dev/null 2>&1")
+      abort "[mcp_inspector] npx not found on PATH. Install Node.js 18+ or use `nvm use 18`."
+    end
+
+    port    = ENV["MCP_INSPECTOR_PORT"] || "3099"
+    api_key = ENV["MCP_INSPECTOR_KEY"]  || "rake-inspector-key"
+    method  = ENV["METHOD"]             || "tools/list"
+
+    server_url, app_id, rest_api_key, master_key = mcp_credentials_or_abort!
+
+    boot = <<~RUBY
+      $LOAD_PATH.unshift(File.expand_path('lib'))
+      require 'parse-stack'
+      Parse.setup(
+        server_url:     #{server_url.inspect},
+        application_id: #{app_id.inspect},
+        api_key:        #{rest_api_key.inspect},
+        master_key:     #{master_key.inspect},
+      )
+      ENV['PARSE_MCP_ENABLED']    = 'true'
+      Parse.mcp_server_enabled    = true
+      Parse::Agent.mcp_enabled    = true
+      require 'parse/agent/mcp_server'
+      Parse::Agent::MCPServer.run(
+        port:        #{port.to_i},
+        host:        '127.0.0.1',
+        permissions: :readonly,
+        api_key:     #{api_key.inspect},
+      )
+    RUBY
+
+    log_path = "tmp/mcp-inspector-server.log"
+    FileUtils.mkdir_p("tmp")
+    pid = Process.spawn("ruby", "-e", boot, out: log_path, err: log_path)
+
+    begin
+      ready = false
+      40.times do
+        sleep 0.25
+        begin
+          uri = URI("http://127.0.0.1:#{port}/health")
+          ready = (Net::HTTP.get_response(uri).code == "200")
+          break if ready
+        rescue Errno::ECONNREFUSED, Errno::EADDRINUSE
+          # retry
+        end
+      end
+      unless ready
+        warn "[mcp_inspector] MCPServer failed to become healthy on port #{port}. Server log:"
+        warn(File.read(log_path)) rescue nil
+        abort "[mcp_inspector] aborting"
+      end
+      puts "[mcp_inspector] MCPServer healthy on http://127.0.0.1:#{port}"
+
+      cmd = [
+        "npx", "--yes", "@modelcontextprotocol/inspector",
+        "--cli", "http://127.0.0.1:#{port}/mcp",
+        "--method", method,
+        "--header", "X-MCP-API-Key:#{api_key}",
+      ]
+      puts "[mcp_inspector] $ #{cmd.join(" ")}"
+      ok = system(*cmd)
+      abort "[mcp_inspector] inspector exited non-zero" unless ok
+      puts "[mcp_inspector] protocol check passed"
+    ensure
+      if pid
+        Process.kill("TERM", pid) rescue nil
+        Process.wait(pid)         rescue nil
+      end
+    end
+  end
+end
+
+task :default => :test
+
+task :console do
+  exec "./bin/console"
+end
+task :c => :console
+
+# ===========================================================================
+# MCP namespace: interactive REPL and one-shot tool dispatch.
+# ===========================================================================
+namespace :mcp do
+  # -------------------------------------------------------------------------
+  # rake mcp:console
+  #
+  # Drops you into an IRB session with a pre-configured Parse::Agent and
+  # MCP helpers bound at the top level. Talk to the agent the same way an
+  # LLM would, but interactively from your terminal.
+  #
+  # Setup:
+  #   - .env (or shell env) provides PARSE_SERVER_URL / PARSE_APP_ID /
+  #     PARSE_API_KEY / PARSE_MASTER_KEY. Defaults match the Docker
+  #     compose harness in scripts/docker/docker-compose.test.yml.
+  #   - Optionally MCP_AGENT_PERMISSIONS=readonly|write|admin
+  #     (default :readonly).
+  #
+  # Bindings available in the REPL:
+  #   agent              — the Parse::Agent instance.
+  #   tools              — print every tool the agent has access to.
+  #   schemas            — print every visible class name.
+  #   t(name, **kwargs)  — invoke a tool, return its result hash.
+  #   q(class_name, ...) — shortcut for t(:query_class, class_name:, **opts).
+  #   count(class_name)  — shortcut for t(:count_objects, class_name:, ...).
+  #   schema(class_name) — shortcut for t(:get_schema, class_name:).
+  #   dispatch(method, params={}) — call MCPDispatcher.call(body:, agent:).
+  #   prompts            — print every registered + builtin prompt.
+  #   render_prompt(name, args={}) — render a prompt to its message envelope.
+  #
+  # Example session:
+  #   $ bundle exec rake mcp:console
+  #   irb> tools
+  #   irb> q("MCPSchoolTeacher", limit: 3)
+  #   irb> count("MCPSchoolStudent")
+  #   irb> dispatch("initialize")
+  # -------------------------------------------------------------------------
+  desc "Interactive MCP REPL: query a Parse::Agent like an LLM would, but with Ruby"
+  task :console do
+    require "irb"
+    require "json"
+    # dotenv is in the Gemfile :test, :development group; load .env if present.
+    begin
+      require "dotenv/load"
+    rescue LoadError
+      # dotenv not installed; rely on shell env vars
+    end
+
+    $LOAD_PATH.unshift(File.expand_path("lib", __dir__))
+    require "parse-stack"
+    require "parse/agent"
+    require "parse/agent/mcp_dispatcher"
+    require "parse/agent/prompts"
+    require "parse/agent/mcp_client"
+
+    server_url, app_id, rest_api_key, master_key = mcp_credentials_or_abort!
+    permissions  = (ENV["MCP_AGENT_PERMISSIONS"] || "readonly").to_sym
+
+    Parse.setup(
+      server_url:     server_url,
+      application_id: app_id,
+      api_key:        rest_api_key,
+      master_key:     master_key,
+    )
+
+    agent = Parse::Agent.new(permissions: permissions)
+
+    # Bind helpers as singleton methods on TOPLEVEL_BINDING so they're
+    # callable bare in the IRB session without a receiver.
+    Object.send(:define_method, :agent) { agent }
+    Object.send(:define_method, :_mcp_agent_const) { agent }
+
+    Object.send(:define_method, :tools) do
+      list = agent.tool_definitions(format: :mcp).map { |t| t[:name] || t["name"] }
+      puts list.sort.join("\n")
+      list.size
+    end
+
+    Object.send(:define_method, :schemas) do
+      result = agent.execute(:get_all_schemas)
+      unless result[:success]
+        puts "get_all_schemas failed: #{result[:error]}"
+        next nil
+      end
+      custom   = (result[:data][:custom]   || []).map { |c| c[:name] }
+      built_in = (result[:data][:built_in] || []).map { |c| c[:name] }
+      puts "Custom:   #{custom.sort.join(", ")}"
+      puts "Built-in: #{built_in.sort.join(", ")}"
+      custom + built_in
+    end
+
+    Object.send(:define_method, :t) do |name, **kwargs|
+      agent.execute(name.to_sym, **kwargs)
+    end
+
+    Object.send(:define_method, :q) do |class_name, **opts|
+      t(:query_class, class_name: class_name, **opts)
+    end
+
+    Object.send(:define_method, :count) do |class_name, **opts|
+      t(:count_objects, class_name: class_name, **opts)
+    end
+
+    Object.send(:define_method, :schema) do |class_name|
+      t(:get_schema, class_name: class_name)
+    end
+
+    Object.send(:define_method, :dispatch) do |method, params = {}|
+      body = { "jsonrpc" => "2.0", "id" => SecureRandom.hex(4), "method" => method.to_s, "params" => params }
+      Parse::Agent::MCPDispatcher.call(body: body, agent: agent)
+    end
+
+    Object.send(:define_method, :prompts) do
+      list = Parse::Agent::Prompts.list.map { |p| p["name"] }
+      puts list.sort.join("\n")
+      list.size
+    end
+
+    Object.send(:define_method, :render_prompt) do |name, args = {}|
+      Parse::Agent::Prompts.render(name.to_s, args.transform_keys(&:to_s))
+    end
+
+    # When LLM_PROVIDER + LLM_API_KEY are in env (e.g. via .env), bind
+    # `mcp` as a conversational client. Lets you do:
+    #   mcp.ask("how many students?")
+    #   _.reply("just for Ms. Vasquez")
+    mcp = nil
+    if ENV["LLM_PROVIDER"]
+      begin
+        mcp = Parse::Agent::MCPClient.new(agent: agent)
+        Object.send(:define_method, :mcp) { mcp }
+      rescue ArgumentError => e
+        puts "[mcp:console] could not initialize MCPClient — #{e.message}"
+        puts "[mcp:console]   set LLM_PROVIDER + LLM_API_KEY in your .env (see .env.sample)"
+      end
+    end
+
+    puts "=" * 70
+    puts "Parse::Agent MCP Console"
+    puts "=" * 70
+    puts "Server:      #{server_url}"
+    puts "Permissions: #{permissions}"
+    puts "Agent:       #{agent.class.name} (#{agent.allowed_tools.size} tools)"
+    puts "LLM client:  " + (mcp ? "#{mcp.provider} / #{mcp.model}" : "DISABLED (set LLM_PROVIDER + LLM_API_KEY to enable mcp.ask)")
+    puts
+    puts "Try:"
+    if mcp
+      puts "  mcp.ask('how many students do we have?')"
+      puts "  _.reply('what about just for Ms. Vasquez?')      # chain replies"
+      puts
+    end
+    puts "  tools                         # list available tools"
+    puts "  schemas                       # list visible Parse classes"
+    puts "  q('User', limit: 3)           # query_class shortcut"
+    puts "  count('Song')                 # count_objects shortcut"
+    puts "  schema('Song')                # get_schema shortcut"
+    puts "  t(:query_class, class_name: 'Song', where: { name: 'X' })"
+    puts "  dispatch('tools/list')        # MCPDispatcher round-trip"
+    puts "  prompts                       # list registered prompts"
+    puts "  render_prompt('parse_conventions')"
+    puts "=" * 70
+
+    IRB.start
+  end
+
+  # -------------------------------------------------------------------------
+  # rake mcp:chat
+  #
+  # Conversational CLI loop — talk to your Parse database via the MCP agent
+  # in plain English. Each turn drives the LLM through tool calls and prints
+  # the final answer; context persists across turns. Like a tiny REPL just
+  # for the MCP agent.
+  #
+  # Setup:
+  #   - .env (or shell env) with LLM_PROVIDER + LLM_API_KEY (see .env.sample)
+  #   - PARSE_SERVER_URL / PARSE_APP_ID / PARSE_API_KEY / PARSE_MASTER_KEY
+  #     (defaults match the Docker compose harness)
+  #
+  # Slash commands inside the loop:
+  #   /reset   — start a fresh conversation (clear history)
+  #   /compact — replace history with an LLM-generated summary (1 extra call)
+  #   /tools   — list available MCP tools
+  #   /trace   — toggle tool-call tracing on/off
+  #   /cost    — show running token + USD cost totals
+  #   /history — print conversation history
+  #   /exit    — leave the chat (also: /quit, exit, quit, Ctrl-D, empty line)
+  # -------------------------------------------------------------------------
+  desc "Conversational CLI: talk to your Parse data via the MCP agent"
+  task :chat do
+    begin
+      require "dotenv/load"
+    rescue LoadError
+    end
+
+    $LOAD_PATH.unshift(File.expand_path("lib", __dir__))
+    require "parse-stack"
+    require "parse/agent"
+    require "parse/agent/mcp_client"
+
+    unless ENV["LLM_PROVIDER"]
+      abort "[mcp:chat] LLM_PROVIDER is not set. Add it to .env (see .env.sample). " \
+            "Supported providers: openai, anthropic, lmstudio."
+    end
+
+    server_url, app_id, rest_api_key, master_key = mcp_credentials_or_abort!
+    Parse.setup(
+      server_url:     server_url,
+      application_id: app_id,
+      api_key:        rest_api_key,
+      master_key:     master_key,
+    )
+
+    permissions = (ENV["MCP_AGENT_PERMISSIONS"] || "readonly").to_sym
+    agent = Parse::Agent.new(permissions: permissions)
+    client = Parse::Agent::MCPClient.new(agent: agent)
+    trace = (ENV["MCP_CHAT_TRACE"] || "false") == "true"
+
+    slash_help = lambda do
+      puts "Slash commands:"
+      puts "  /help    — print this list"
+      puts "  /reset   — clear conversation history"
+      puts "  /compact — replace history with an LLM-generated summary"
+      puts "  /tools   — list MCP tools the agent has access to"
+      puts "  /trace   — toggle per-turn tool-call tracing on/off"
+      puts "  /cost    — show running token + USD totals (and last turn)"
+      puts "  /history — print the conversation log"
+      puts "  /exit    — leave (also /quit, exit, quit, Ctrl-D, empty line)"
+    end
+
+    puts "=" * 70
+    puts "Parse MCP Chat — #{client.provider} / #{client.model}"
+    puts "Permissions: #{permissions}  |  Trace: #{trace ? "on" : "off"}"
+    puts "Type your question. Type /help for slash commands."
+    puts "=" * 70
+
+    loop do
+      print "\n> "
+      line = $stdin.gets
+      break if line.nil?  # Ctrl-D
+      line = line.strip
+      next if line.empty?
+
+      case line
+      when "/exit", "/quit", "exit", "quit"
+        break
+      when "/help"
+        slash_help.call
+        next
+      when "/reset"
+        client.reset!
+        puts "[conversation cleared]"
+        next
+      when "/compact"
+        before = client.usage.total_tokens
+        summary = client.compact!
+        if summary.empty?
+          puts "[nothing to compact]"
+        else
+          delta = client.usage.total_tokens - before
+          puts "[compacted; +#{delta} tokens spent on summary]"
+          puts "  summary: #{summary[0, 200]}#{summary.length > 200 ? "…" : ""}"
+        end
+        next
+      when "/tools"
+        puts agent.tool_definitions(format: :mcp).map { |t| t[:name] || t["name"] }.sort.join("\n")
+        next
+      when "/trace"
+        trace = !trace
+        puts "[trace #{trace ? "on" : "off"}]"
+        next
+      when "/cost"
+        u = client.usage
+        last = client.last_call_usage
+        printf "  session: %d in + %d out = %d tokens   $%.4f\n",
+               u.prompt_tokens, u.completion_tokens, u.total_tokens, u.cost_usd
+        if last
+          printf "  last:    %d in + %d out = %d tokens   $%.6f\n",
+                 last.prompt_tokens, last.completion_tokens, last.total_tokens, last.cost_usd
+        end
+        next
+      when "/history"
+        client.history.each_with_index do |m, i|
+          puts "  #{i + 1}. [#{m[:role]}] #{m[:content].to_s[0, 120]}"
+        end
+        next
+      end
+
+      begin
+        result = client.ask(line, reset: false)
+        if trace && result.tool_calls.any?
+          puts "─── tool calls ───"
+          result.tool_calls.each_with_index do |tc, i|
+            args = tc[:arguments].is_a?(Hash) ? tc[:arguments].inspect : tc[:arguments].to_s
+            puts "  #{i + 1}. #{tc[:name]}(#{args})"
+          end
+        end
+        puts
+        puts result.text.to_s.empty? ? "[empty response]" : result.text
+        if trace && result.usage && result.usage.total_tokens.positive?
+          printf "[%d tokens / $%.6f this turn   session: %d / $%.4f]\n",
+                 result.usage.total_tokens, result.usage.cost_usd,
+                 client.usage.total_tokens, client.usage.cost_usd
+        end
+      rescue Interrupt
+        puts "\n[interrupted]"
+        next
+      rescue => e
+        puts "[error] #{e.class}: #{e.message}"
+      end
+    end
+
+    puts "\nbye"
+  end
+
+  # -------------------------------------------------------------------------
+  # rake "mcp:tool[query_class,{\"class_name\":\"Song\",\"limit\":3}]"
+  #
+  # One-shot tool dispatch from the command line. The first arg is the tool
+  # name; the second is a JSON object of keyword arguments. Result printed
+  # as pretty JSON. Useful for ad-hoc smoke checks without spinning up IRB.
+  # -------------------------------------------------------------------------
+  desc "One-shot tool call: rake 'mcp:tool[name,jsonArgs]'"
+  task :tool, [:name, :args_json] do |_t, args|
+    begin
+      require "dotenv/load"
+    rescue LoadError
+    end
+    require "json"
+    require "parse-stack"
+    require "parse/agent"
+
+    tool_name = (args[:name] || abort("usage: rake 'mcp:tool[name,jsonArgs]'")).to_sym
+    raw       = args[:args_json] || "{}"
+    parsed    = JSON.parse(raw)
+    kwargs    = parsed.transform_keys(&:to_sym)
+
+    server_url, app_id, rest_api_key, master_key = mcp_credentials_or_abort!
+    Parse.setup(
+      server_url:     server_url,
+      application_id: app_id,
+      api_key:        rest_api_key,
+      master_key:     master_key,
+    )
+
+    agent = Parse::Agent.new(permissions: (ENV["MCP_AGENT_PERMISSIONS"] || "readonly").to_sym)
+    result = agent.execute(tool_name, **kwargs)
+    puts JSON.pretty_generate(result)
+    exit(result[:success] ? 0 : 1)
+  end
+end
+
+desc "List undocumented methods"
+task "yard:stats" do
+  exec "yard stats --list-undoc"
+end
+
+desc "Start the yard server"
+task "docs" do
+  exec "rm -rf ./yard && yard server --reload"
+end
+
+YARD::Rake::YardocTask.new do |t|
+  t.files = ["lib/**/*.rb"]   # optional
+  t.options = ["-o", "doc/parse-stack"] # optional
+  t.stats_options = ["--list-undoc"]         # optional
+end

data/bin/console

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require 'debug/prelude'
+require 'dotenv'
+require "parse/stack"
+
+Dotenv.load
+
+def setup
+  Parse.setup # cache: 'redis://localhost:6379'
+
+  puts "[ParseServerURL] #{Parse.client.server_url}"
+  puts "[ParseAppID]     #{Parse.client.app_id}"
+
+  if Parse.client.master_key.present?
+    Parse.auto_generate_models!.each do |model|
+      puts "Generated #{model}"
+    end
+  end
+
+end
+puts "Type 'setup' to connect to Parse-Server"
+
+# Create shortnames
+Parse.use_shortnames!
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+require "pry"
+Pry.start
+
+#
+# require "irb"
+# IRB.start
+#Rack::Server.start :app => HelloWorldApp