parse-stack-next 5.5.3 → 5.5.5

data/Rakefile

@@ -1,825 +0,0 @@
-#!/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:29337/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? ? "psnextItAppId" : app_id)
-      rest_api_key = (rest_api_key.to_s.empty? ? "myApiKey" : rest_api_key)
-      master_key   = (master_key.to_s.empty? ? "psnextItMasterKey" : 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
-
-# Resolve the identity for `rake client:console`. Returns a session-token String,
-# or nil to mean "anonymous" (no token, no master). Order: PARSE_SESSION_TOKEN,
-# PARSE_CLIENT_ANONYMOUS=true, PARSE_LOGIN_USER (+PARSE_LOGIN_PASSWORD), else
-# prompt for login / token / anon. The login path uses the configured default
-# client (the master client set up just before this is called).
-def client_console_token!
-  token = ENV["PARSE_SESSION_TOKEN"].to_s.strip
-  return token unless token.empty?
-  return nil if ENV["PARSE_CLIENT_ANONYMOUS"].to_s == "true"
-
-  user = ENV["PARSE_LOGIN_USER"].to_s.strip
-  if user.empty?
-    print "Identity? [login/token/anon] (login): "
-    case $stdin.gets.to_s.strip.downcase
-    when "anon", "anonymous" then return nil
-    when "token"
-      print "Session token (r:...): "
-      t = $stdin.gets.to_s.strip
-      return t.empty? ? nil : t
-    else
-      print "Username (blank for anonymous): "
-      user = $stdin.gets.to_s.strip
-      return nil if user.empty?
-    end
-  end
-
-  pwd = ENV["PARSE_LOGIN_PASSWORD"].to_s
-  if pwd.empty?
-    begin
-      require "io/console"
-      print "Password for #{user}: "
-      pwd = $stdin.noecho(&:gets).to_s
-      puts
-    rescue LoadError, IOError, SystemCallError
-      # io/console missing, or stdin is not a TTY (piped input raises
-      # Errno::ENOTTY, a SystemCallError — not an IOError). Fall back to a
-      # plain read; warn that it will echo.
-      warn "[client:console] WARNING: cannot disable echo; password will be visible."
-      print "Password for #{user}: "
-      pwd = $stdin.gets.to_s
-    end
-  end
-  u = console_login_with_optional_mfa(user, pwd.chomp)
-  abort "[client:console] login failed for #{user.inspect}" if u.nil? || u.session_token.to_s.empty?
-  puts "Logged in as #{u.username} (#{u.id})."
-  u.session_token
-end
-
-# Log `user` in, transparently handling an MFA-enrolled account. If the server
-# reports that additional MFA auth is required, prompt for a TOTP / recovery
-# code (or read +PARSE_LOGIN_MFA+ for non-interactive use) and retry via
-# {Parse::User.login_with_mfa}. Returns a logged-in {Parse::User}, or nil when
-# the credentials themselves are rejected (so the caller's "login failed" abort
-# still fires for a bad password).
-def console_login_with_optional_mfa(user, pwd)
-  # Parse Server signals "this account needs an MFA token" two ways depending on
-  # the error code path: a returned error response ("Missing additional
-  # authData ...") or a raised Parse::Error for the OTHER_CAUSE (code <= 100)
-  # variant. Treat both as "prompt for MFA"; anything else is a real credential
-  # failure and must NOT trigger an MFA prompt.
-  mfa_indicator = /additional\s+authData|missing.*mfa|\bMFA\b/i
-  begin
-    response = Parse.client.login(user, pwd)
-    if response.success?
-      return Parse::User.with_authdata_trust { Parse::User.build(response.result) }
-    end
-    return nil unless response.error.to_s.match?(mfa_indicator)
-  rescue Parse::Error, Parse::Client::ResponseError => e
-    raise unless e.message.to_s.match?(mfa_indicator)
-  end
-
-  token = ENV["PARSE_LOGIN_MFA"].to_s.strip
-  if token.empty?
-    print "MFA token (authenticator code or recovery code): "
-    token = $stdin.gets.to_s.strip
-  end
-  abort "[client:console] MFA token required for #{user.inspect}" if token.empty?
-
-  # A wrong/expired token can surface either as Parse::MFA::VerificationError or,
-  # depending on the server error code path, as a generic Parse::Error (e.g.
-  # ServiceUnavailableError for the OTHER_CAUSE code) or a nil return. Since a
-  # token was supplied here, treat any failure as an MFA verification failure
-  # and abort cleanly rather than letting an unhandled exception escape.
-  result =
-    begin
-      Parse::User.login_with_mfa(user, pwd, token)
-    rescue Parse::MFA::VerificationError, Parse::Error => e
-      abort "[client:console] MFA verification failed for #{user.inspect}: #{e.message}"
-    end
-  abort "[client:console] MFA verification failed for #{user.inspect}" if result.nil?
-  result
-end
-
-# Default test task runs all tests with Docker enabled.
-#
-# `*disruptive*` tests are EXCLUDED here: they stop/restart the shared
-# Parse Server container, which would flake any other test loaded into the
-# same process. Run them on their own via `rake test:integration:disruptive`.
-Rake::TestTask.new do |t|
-  ENV['PARSE_TEST_USE_DOCKER'] = 'true'
-  t.libs << "lib/parse/stack"
-  t.test_files = FileList["test/lib/**/*_test.rb"].exclude("test/lib/**/*disruptive*")
-  t.warning = false
-  t.verbose = true
-end
-
-# Shared runner for the file-per-process test tasks. Each test file runs in its
-# own Ruby process (isolation against the shared Parse Server); output streams
-# live, and — for trackability — a PASS/FAIL + duration line per file is printed
-# to STDOUT *and* appended to a progress log you can `tail -f` from another
-# shell while the run is in flight (works even when the run is backgrounded or
-# piped, where STDOUT would otherwise buffer until completion).
-#
-# Env knobs:
-#   TEST_PATTERN=<substr>       run only files whose path includes <substr>
-#                               (e.g. TEST_PATTERN=webhook)
-#   CONTINUE_ON_FAILURE=false   stop at the first failing file
-#                               (default: run them all, then list every failure)
-#
-# Exits non-zero if any file failed.
-def run_test_files!(label, files, log:)
-  $stdout.sync = true
-  require "fileutils"
-  if (pattern = ENV["TEST_PATTERN"].to_s).length.positive?
-    files = files.select { |f| f.include?(pattern) }
-    puts "TEST_PATTERN=#{pattern} -> #{files.length} matching file(s)"
-  end
-  continue = ENV.fetch("CONTINUE_ON_FAILURE", "true") != "false"
-  FileUtils.mkdir_p(File.dirname(log))
-  total = files.length
-  started = Time.now
-  results = []
-  File.write(log, "#{label}: #{total} files, started #{started}\n")
-  puts "\n>> #{label}: #{total} files (progress log: #{log})"
-
-  files.each_with_index do |file, i|
-    n = i + 1
-    puts "\n" + "=" * 80
-    puts "[#{n}/#{total}] #{file}"
-    puts "=" * 80
-    t0 = Time.now
-    # Always go through `bundle exec` so the locked gem versions win. With a
-    # bare `ruby`, RubyGems activates the newest installed minitest (6.0.x),
-    # which dropped the bundled `minitest/mock`; the standalone `minitest-mock`
-    # gem then can't co-activate and `test_helper.rb` fails to load every file.
-    ok = system("PARSE_TEST_USE_DOCKER=true bundle exec ruby -Ilib:test #{file}")
-    dt = Time.now - t0
-    results << [file, ok, dt]
-    summary = format("[%d/%d] %-4s %7.1fs  %s", n, total, ok ? "PASS" : "FAIL", dt, file)
-    puts summary
-    File.open(log, "a") { |f| f.puts summary }
-    if !ok && !continue
-      File.open(log, "a") { |f| f.puts "STOPPED at first failure (CONTINUE_ON_FAILURE=false)" }
-      break
-    end
-  end
-
-  elapsed = Time.now - started
-  passed = results.count { |_, ok, _| ok }
-  failed = results.reject { |_, ok, _| ok }
-  footer = format("%s: %d/%d passed in %.1fs (%.1f min)",
-                  label, passed, results.length, elapsed, elapsed / 60.0)
-  puts "\n" + "=" * 80
-  puts footer
-  unless failed.empty?
-    puts "Failed (#{failed.length}):"
-    failed.each { |f, _, d| puts format("  FAIL %7.1fs  %s", d, f) }
-  end
-  puts "=" * 80
-  File.open(log, "a") do |f|
-    f.puts footer
-    failed.each { |ff, _, d| f.puts format("  FAIL %7.1fs  %s", d, ff) }
-  end
-  exit(1) unless failed.empty?
-end
-
-# Integration tests require Docker
-namespace :test do
-  desc "Run all integration tests (requires Docker). " \
-       "Knobs: TEST_PATTERN=<substr>, CONTINUE_ON_FAILURE=false."
-  task :integration do
-    # Disruptive tests (server stop/restart) are run separately via
-    # `test:integration:disruptive` so they never interleave with — and
-    # flake — the rest of the integration suite against the shared server.
-    files = FileList["test/lib/**/*integration_test.rb"]
-              .exclude("test/lib/**/*disruptive*")
-    run_test_files!("Integration tests", files, log: "tmp/integration-progress.log")
-  end
-
-  desc "Run unit tests only (no Docker required). " \
-       "Knobs: TEST_PATTERN=<substr>, CONTINUE_ON_FAILURE=false."
-  task :unit do
-    files = FileList["test/lib/**/*_test.rb"]
-              .exclude("test/lib/**/*integration_test.rb")
-              .exclude("test/lib/**/*disruptive*")
-    run_test_files!("Unit tests", files, log: "tmp/unit-progress.log")
-  end
-
-  namespace :integration do
-    desc "Run DISRUPTIVE integration tests (stop/restart the Parse Server " \
-         "container). Run in isolation — these are excluded from the normal " \
-         "test / test:integration / test:unit runs."
-    task :disruptive do
-      disruptive_files = FileList["test/lib/**/*disruptive*_test.rb"]
-
-      if disruptive_files.empty?
-        puts "No disruptive test files found."
-        next
-      end
-
-      puts "Running #{disruptive_files.length} disruptive test file(s)..."
-      disruptive_files.each_with_index do |file, index|
-        puts "\n" + "=" * 80
-        puts "Running disruptive test #{index + 1}/#{disruptive_files.length}: #{file}"
-        puts "=" * 80
-        # Each file runs in its own process so a server outage in one cannot
-        # bleed into the next.
-        system("PARSE_TEST_USE_DOCKER=true bundle exec ruby -Ilib:test #{file}") || begin
-          # A disruptive test may have left the server down on failure; bring
-          # it back so a follow-up run / other tasks start from a clean state.
-          system("docker start #{ENV["PSNEXT_PREFIX"] || "psnext-it"}-server", out: IO::NULL, err: IO::NULL)
-          exit(1)
-        end
-      end
-      puts "\n✅ All disruptive tests completed successfully!"
-    end
-  end
-
-  desc "List all available test files"
-  task :list do
-    puts "\nIntegration Tests:"
-    FileList["test/lib/**/*integration_test.rb"].exclude("test/lib/**/*disruptive*").each { |f| puts "  #{f}" }
-
-    puts "\nDisruptive Integration Tests (run via test:integration:disruptive):"
-    FileList["test/lib/**/*disruptive*_test.rb"].each { |f| puts "  #{f}" }
-
-    puts "\nUnit Tests:"
-    FileList["test/lib/**/*_test.rb"]
-      .exclude("test/lib/**/*integration_test.rb")
-      .exclude("test/lib/**/*disruptive*")
-      .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
-
-# rake client:console — IRB whose DEFAULT client is a non-master client bound to
-# a user's session, so every model query runs as that user (ACL/CLP enforced).
-# Identity: PARSE_SESSION_TOKEN, or PARSE_LOGIN_USER/PARSE_LOGIN_PASSWORD, else
-# prompt. Connection env matches the other tasks; the master key is used only to
-# log in. Helpers in the REPL: client, whoami, as_master { … }.
-namespace :client do
-  desc "Interactive console authenticated as a Parse user (session token or login), not master"
-  task :console do
-    require "irb"
-    begin; require "dotenv/load"; rescue LoadError; end
-    $LOAD_PATH.unshift(File.expand_path("lib", __dir__))
-    require "parse-stack"
-
-    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)
-    master_client = Parse.client
-    token = client_console_token! # String, or nil for anonymous
-
-    # Models memoize their resolved client at the class level (`@client ||=`),
-    # so swapping clients[:default] alone is NOT enough — every swap must also
-    # drop those cached ivars or already-touched classes keep the old client.
-    reset_client_caches = lambda do
-      next unless defined?(Parse::Object)
-      [Parse::Object, *Parse::Object.descendants, Parse::Query].each do |k|
-        k.remove_instance_variable(:@client) if k.instance_variable_defined?(:@client)
-      end
-    end
-
-    # Make a non-master client (session-bound, or anonymous) the default so
-    # every model query runs as the user.
-    user_client = token ? master_client.become(token) : master_client.anonymous
-    Parse::Client.clients[:default] = user_client
-    reset_client_caches.call
-
-    Object.send(:define_method, :client) { user_client }
-    # Redacted: GET /users/me returns a Parse::User carrying the live
-    # sessionToken, and Parse::Object has no redacted #inspect, so returning the
-    # raw object would print the token in the REPL. Hand back a safe summary.
-    Object.send(:define_method, :whoami) do
-      next "anonymous (no session)" unless token
-      r = user_client.current_user(token)
-      next "whoami failed: #{r.error}" unless r.success?
-      u = r.result
-      { "username" => u["username"], "objectId" => u["objectId"], "session_token" => "[FILTERED]" }
-    rescue StandardError => e
-      "whoami failed: #{e.message}"
-    end
-    # Escalate to the master key for the block, then restore the user client.
-    # Both swaps must reset the class client caches (see reset_client_caches),
-    # otherwise a class touched inside the block keeps master afterward, or a
-    # previously-touched class never escalates. Already-instantiated Parse::Query
-    # objects held in REPL locals keep their own client and are not reset.
-    Object.send(:define_method, :as_master) do |&blk|
-      Parse::Client.clients[:default] = master_client
-      reset_client_caches.call
-      blk.call
-    ensure
-      Parse::Client.clients[:default] = user_client
-      reset_client_caches.call
-    end
-
-    mode = token ? "a USER" : "ANONYMOUS"
-    puts "parse-stack-next client console — as #{mode} (no master key). Helpers: client, whoami, as_master { }."
-    ARGV.clear
-    IRB.start
-  end
-end
-
-desc "List undocumented methods"
-task "yard:stats" do
-  exec "yard stats --list-undoc"
-end
-
-desc "Start the yard server"
-task "docs" do
-  # `-t docs/yard-template` is required: `yard server` does not honor
-  # the --template-path line in .yardopts (that's only read by
-  # `yard doc`), so the custom theme overlay only takes effect when
-  # the path is passed on the command line.
-  exec "rm -rf ./yard && yard server --reload -t docs/yard-template"
-end
-
-YARD::Rake::YardocTask.new do |t|
-  t.files = ["lib/**/*.rb"]   # optional
-  t.options = ["-o", "doc/parse-stack-next"] # optional
-  t.stats_options = ["--list-undoc"]         # optional
-end