mendix-ruby-bridge 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb1eb419fc9e16b0f10171eab510dc761911deb7cdde1b4428e9d239d605eeb9
-  data.tar.gz: 72953444a53d27e636683de9d0578fff6da451c2dd76a65c79ceb76de13d3b9d
+  metadata.gz: 767361072737fe4fd5c02587af41776895fa64a24c143ec599ad54df874bd1f8
+  data.tar.gz: 50da6cebeb94f6fb0ab8ee1f5418488b2d9e148b7d30a1fb773eebda58b5af04
 SHA512:
-  metadata.gz: 8c19e5e823cac18f93fe901340b856621af47b5aad2a85151d2387bbad230eb80f0f64e6a4fb9dcbb81939f3f593631385762311d2de7cf7bc6d71ffb49595c1
-  data.tar.gz: 46c757f8cb088baf81bfb76c1718de09ba9b0d171ec316eba7a08b0b4e3d28b481605f0081e479404f6daf4138d1e2d6fd431728e2f248ea103dff1b0797c09b
+  metadata.gz: ea4cc6ba22ea7d9f075549da294d77e49afd478d851f2388c7685384783c83e64ab9f89c607ebe707d6204c1e01d2a5826fd13d8ec8692c0d16569bb217e0de3
+  data.tar.gz: 042d3e85502ddae7a63e8c553c3e6a720335b595fb8862d072257ede8d306a0fd67d6ecb8d6f66cd18d4ecec5dbd81425692d395ace4fde2b2f9f883b090cbeb

data/bin/setup-tools

@@ -16,25 +16,10 @@ download_url="https://github.com/mendixlabs/mxcli/releases/download/v${version}/
 
 if [[ -x "$executable" ]]; then
   echo "mxcli $version is already installed"
-else
-  mkdir -p "$install_dir"
-  curl --fail --location "$download_url" --output "$executable"
-  chmod +x "$executable"
-  "$executable" --version
+  exit 0
 fi
 
-echo "Installing desktop dependencies (gtk3, webkit2-gtk)..."
-if command -v pacman &>/dev/null; then
-  sudo pacman -S --needed --noconfirm gtk3 gobject-introspection webkit2gtk-4.1
-  gem install gtk3 webkit2-gtk
-elif command -v apt-get &>/dev/null; then
-  sudo apt-get install -y libgtk-3-dev libgirepository1.0-dev libwebkit2gtk-4.1-dev
-  gem install gtk3 webkit2-gtk
-elif command -v dnf &>/dev/null; then
-  sudo dnf install -y gtk3-devel gobject-introspection-devel webkit2gtk4.1-devel
-  gem install gtk3 webkit2-gtk
-else
-  echo "Package manager not detected; installing via gem (system libs must already be present)..."
-  gem install gtk3 webkit2-gtk
-fi
-echo "Desktop dependencies installed."
+mkdir -p "$install_dir"
+curl --fail --location "$download_url" --output "$executable"
+chmod +x "$executable"
+"$executable" --version

data/lib/mendix_bridge/alter_page_builder.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module MendixBridge
+  # Builds ALTER PAGE / ALTER SNIPPET MDL statements from a structured list of
+  # operations.  Each operation is a Hash with an "op" key and operation-
+  # specific fields:
+  #
+  #   { "op" => "set",          "widget" => "btnSave",
+  #     "props" => { "Caption" => "Save & Close", "ButtonStyle" => "Success" } }
+  #
+  #   { "op" => "insert_after", "widget" => "tbEmail",
+  #     "body" => "textbox tbPhone (Label: 'Phone', Attribute: Phone)" }
+  #
+  #   { "op" => "insert_before","widget" => "btnCancel",
+  #     "body" => "actionbutton btnBack (Caption: 'Back', Action: close_page)" }
+  #
+  #   { "op" => "drop",         "widgets" => ["tbUnused", "lblOld"] }
+  #
+  #   { "op" => "replace",      "widget" => "tbName",
+  #     "body" => "textarea taName (Label: 'Name', Attribute: Name)" }
+  #
+  #   { "op" => "set_layout",   "layout" => "Atlas_Core.Atlas_Sidebar_Full" }
+  #
+  #   { "op" => "add_variable", "name" => "counter",
+  #     "type" => "Integer",    "default" => "0" }
+  #
+  #   { "op" => "drop_variable","name" => "counter" }
+  #
+  # Validation errors are returned as an array of strings from `validate`.
+  # `build` raises `ArgumentError` when there are errors.
+  module AlterPageBuilder
+    VALID_OPS = %w[
+      set insert_after insert_before drop replace set_layout add_variable drop_variable
+    ].freeze
+
+    IDENTIFIER = /\A[A-Za-z_]\w*\z/
+    QN_PATTERN = /\A[A-Za-z_]\w*\.[A-Za-z_]\w*\z/
+    LAYOUT_QN  = /\A[A-Za-z_]\w*\.[A-Za-z_]\w*\z/
+
+    # Build an ALTER PAGE MDL string from `qn` and an array of `operations`.
+    # Raises ArgumentError if any operation is invalid.
+    # Pass `known_names:` (array of widget name strings from the page tree) to
+    # enable widget-name existence checks.  Omit it to skip those checks.
+    def self.build(qn:, operations:, known_names: nil)
+      errors = validate(operations, known_names: known_names)
+      raise ArgumentError, errors.join("; ") if errors.any?
+
+      lines = operations.map { |op| build_operation(op) }.compact
+      "ALTER PAGE #{qn} {\n#{lines.join("\n")}\n};\n"
+    end
+
+    # Returns an array of human-readable error strings, or [] if valid.
+    def self.validate(operations, known_names: nil)
+      return ["operations must be an array"] unless operations.is_a?(Array)
+
+      errors = []
+      operations.each_with_index do |op, i|
+        prefix = "operation[#{i}]"
+        unless op.is_a?(Hash)
+          errors << "#{prefix}: must be a hash"
+          next
+        end
+
+        kind = op["op"].to_s
+        unless VALID_OPS.include?(kind)
+          errors << "#{prefix}: unknown op '#{kind}' (valid: #{VALID_OPS.join(", ")})"
+          next
+        end
+
+        case kind
+        when "set"
+          errors << "#{prefix}: 'widget' required" unless op["widget"].is_a?(String)
+          errors << "#{prefix}: 'props' must be a non-empty hash" unless
+            op["props"].is_a?(Hash) && op["props"].any?
+          check_widget_exists(prefix, op["widget"], known_names, errors)
+
+        when "insert_after", "insert_before"
+          errors << "#{prefix}: 'widget' required" unless op["widget"].is_a?(String)
+          errors << "#{prefix}: 'body' required (MDL widget definition)" unless
+            op["body"].is_a?(String) && !op["body"].strip.empty?
+          check_widget_exists(prefix, op["widget"], known_names, errors)
+
+        when "drop"
+          unless op["widgets"].is_a?(Array) && op["widgets"].all? { |w| w.is_a?(String) }
+            errors << "#{prefix}: 'widgets' must be an array of strings"
+            next
+          end
+          op["widgets"].each { |w| check_widget_exists(prefix, w, known_names, errors) }
+
+        when "replace"
+          errors << "#{prefix}: 'widget' required" unless op["widget"].is_a?(String)
+          errors << "#{prefix}: 'body' required (MDL widget definition)" unless
+            op["body"].is_a?(String) && !op["body"].strip.empty?
+          check_widget_exists(prefix, op["widget"], known_names, errors)
+
+        when "set_layout"
+          unless op["layout"].is_a?(String) && op["layout"].match?(LAYOUT_QN)
+            errors << "#{prefix}: 'layout' must be a qualified name (Module.Layout)"
+          end
+
+        when "add_variable"
+          errors << "#{prefix}: 'name' must be a valid identifier" unless
+            op["name"].is_a?(String) && op["name"].match?(IDENTIFIER)
+          errors << "#{prefix}: 'type' required" unless op["type"].is_a?(String)
+
+        when "drop_variable"
+          errors << "#{prefix}: 'name' must be a valid identifier" unless
+            op["name"].is_a?(String) && op["name"].match?(IDENTIFIER)
+        end
+      end
+
+      errors
+    end
+
+    # -------------------------------------------------------------------------
+    private_class_method def self.check_widget_exists(prefix, name, known_names, errors)
+      return unless known_names && name.is_a?(String)
+
+      unless known_names.include?(name)
+        errors << "#{prefix}: widget '#{name}' not found in page (known: #{known_names.sort.join(", ")})"
+      end
+    end
+
+    private_class_method def self.build_operation(op)
+      case op["op"]
+      when "set"
+        props = render_props(op["props"])
+        "  SET (#{props}) ON #{op["widget"]};"
+
+      when "insert_after"
+        "  INSERT AFTER #{op["widget"]} {\n#{indent_body(op["body"])}\n  };"
+
+      when "insert_before"
+        "  INSERT BEFORE #{op["widget"]} {\n#{indent_body(op["body"])}\n  };"
+
+      when "drop"
+        names = Array(op["widgets"]).join(", ")
+        "  DROP WIDGET #{names};"
+
+      when "replace"
+        "  REPLACE #{op["widget"]} WITH {\n#{indent_body(op["body"])}\n  };"
+
+      when "set_layout"
+        "  SET Layout #{op["layout"]};"
+
+      when "add_variable"
+        default = op["default"] ? " = '#{escape_mdl(op["default"].to_s)}'" : ""
+        "  ADD VARIABLES $#{op["name"]}: #{op["type"]}#{default};"
+
+      when "drop_variable"
+        "  DROP VARIABLES $#{op["name"]};"
+      end
+    end
+
+    private_class_method def self.render_props(props)
+      props.map do |key, value|
+        rendered =
+          case value
+          when String  then value.match?(/\A[A-Za-z_$][\w.$\/]*\z/) ? value : "'#{escape_mdl(value)}'"
+          when Integer, Float then value.to_s
+          when TrueClass, FalseClass then value.to_s
+          else "'#{escape_mdl(value.to_s)}'"
+          end
+        "#{key}: #{rendered}"
+      end.join(", ")
+    end
+
+    private_class_method def self.indent_body(body)
+      body.to_s.strip.lines.map { |line| "    #{line.rstrip}" }.join("\n")
+    end
+
+    private_class_method def self.escape_mdl(str)
+      str.to_s.gsub("'", "''")
+    end
+  end
+end

data/lib/mendix_bridge/backend_server.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
 require "json"
+require "net/http"
 require "open3"
+require "socket"
 require "tempfile"
 require "time"
+require "timeout"
 require "webrick"
 
 module MendixBridge
@@ -40,6 +43,11 @@ module MendixBridge
       @docker_running = false
       @auth_user = nil
       @run_cmd_override = run_cmd
+      @xas_log = []
+      @xas_mutex = Mutex.new
+      @database_mutex = Mutex.new
+      @xas_proxy_enabled = false
+      @xas_target_port = nil
       validate!
       @server = WEBrick::HTTPServer.new(
         BindAddress: bind,
@@ -86,6 +94,7 @@ module MendixBridge
       end
       @server.mount_proc("/api/git") { |request, response| git_route(request, response) }
       @server.mount_proc("/api/page") { |request, response| page_route(request, response) }
+      @server.mount_proc("/api/alter") { |request, response| alter_route(request, response) }
       @server.mount_proc("/api/flow") { |request, response| flow_route(request, response) }
       @server.mount_proc("/api/drafts") { |_request, response| drafts(response) }
       @server.mount_proc("/api/apply") { |request, response| apply_draft_route(request, response) }
@@ -99,6 +108,8 @@ module MendixBridge
       @server.mount_proc("/api/marketplace/install") do |request, response|
         marketplace_install(request, response)
       end
+      @server.mount_proc("/api/xas") { |request, response| xas_control(request, response) }
+      @server.mount_proc("/xas") { |request, response| xas_proxy(request, response) }
       @server.mount(
         "/",
         WEBrick::HTTPServlet::FileHandler,
@@ -327,13 +338,49 @@ module MendixBridge
 
       result =
         case [request.request_method, action]
-        when ["GET", "status"] then workflow.status
-        when ["GET", "branches"] then { "branches" => workflow.branches, "current" => workflow.status["branch"] }
-        when ["GET", "stash"] then { "stash" => workflow.stash_list.lines.map(&:strip).reject(&:empty?) }
-        when ["POST", "fetch"] then workflow.fetch && workflow.status
-        when ["POST", "switch"] then workflow.switch(payload.fetch("branch"), studio_closed: closed)
-        when ["POST", "create"] then workflow.create(payload.fetch("branch"), studio_closed: closed)
-        when ["POST", "commit"] then workflow.commit(payload.fetch("message"), studio_closed: closed)
+        when ["GET",  "status"]       then workflow.status
+        when ["GET",  "branches"]
+          {
+            "branches" => workflow.branches,
+            "current" => workflow.status["branch"],
+            "remotes" => workflow.remote_names
+          }
+        when ["GET",  "tags"]         then { "tags" => workflow.tags }
+        when ["GET",  "worktrees"]    then { "worktrees" => workflow.worktrees, "root" => workflow.root }
+        when ["GET",  "stash"]        then { "stash" => workflow.stash_list.lines.map(&:strip).reject(&:empty?) }
+        when ["GET",  "log"]
+          max = [[(request.query["max"] || "200").to_i, 1].max, 500].min
+          { "commits" => workflow.log(max:) }
+        when ["GET",  "file-status"]  then { "files" => workflow.file_status }
+        when ["POST", "fetch"]        then workflow.fetch && workflow.status
+        when ["POST", "switch"]       then workflow.switch(payload.fetch("branch"), studio_closed: closed)
+        when ["POST", "create"]
+          workflow.create(
+            payload.fetch("branch"),
+            studio_closed: closed,
+            start_point: payload["start_point"],
+            carry_changes: payload["carry_changes"] == true
+          )
+        when ["POST", "command"]
+          workflow.terminal_command(payload.fetch("command"), studio_closed: closed)
+        when ["POST", "commit"]       then workflow.commit(payload.fetch("message"), studio_closed: closed)
+        when ["POST", "commit-staged"] then workflow.commit_staged(payload.fetch("message"), studio_closed: closed)
+        when ["POST", "stage"]        then workflow.stage(payload.fetch("path"))
+        when ["POST", "unstage"]      then workflow.unstage(payload.fetch("path"))
+        when ["POST", "discard"]      then workflow.discard(payload.fetch("path"))
+        when ["POST", "push"]         then workflow.push
+        when ["POST", "remote"]       then workflow.add_remote(payload.fetch("name"), payload.fetch("url"))
+        when ["POST", "pull"]         then workflow.pull(studio_closed: closed)
+        when ["POST", "cherry-pick"]  then workflow.cherry_pick(payload.fetch("sha"), studio_closed: closed)
+        when ["POST", "revert"]       then workflow.revert_commit(payload.fetch("sha"), studio_closed: closed)
+        when ["POST", "reset"]        then workflow.reset_to(payload.fetch("sha"), mode: payload.fetch("mode", "mixed"), studio_closed: closed)
+        when ["POST", "tag"]
+          workflow.create_tag(payload.fetch("name"), sha: payload["sha"], message: payload["message"])
+        when ["POST", "delete-tag"]    then workflow.delete_tag(payload.fetch("name"))
+        when ["POST", "delete-branch"]
+          workflow.delete_branch(payload.fetch("name"), force: payload["force"] == true)
+        when ["POST", "merge"]        then workflow.merge(payload.fetch("branch"), studio_closed: closed)
+        when ["POST", "rebase"]       then workflow.rebase(payload.fetch("branch"), studio_closed: closed)
         when ["POST", "stash"]
           workflow.stash_push(
             studio_closed: closed,
@@ -462,7 +509,7 @@ module MendixBridge
       persist_page_draft(qn, content, mdl, ok, message)
       json(
         response,
-        { ok:, mdl:, message: ok ? "Page MDL validated and draft saved." : message },
+        { ok:, mdl:, message: ok ? "Page changes validated and saved." : message },
         status: ok ? 200 : 422
       )
     rescue KeyError => error
@@ -489,7 +536,7 @@ module MendixBridge
       persist_draft("flow-plans.json", qn, "body" => body, "mdl" => mdl, "valid" => ok, "message" => message)
       json(
         response,
-        { ok:, mdl:, message: ok ? "Flow MDL validated and draft saved." : message },
+        { ok:, mdl:, message: ok ? "Flow changes validated and saved." : message },
         status: ok ? 200 : 422
       )
     rescue KeyError => error
@@ -521,8 +568,9 @@ module MendixBridge
         response,
         {
           entities: read.call("visual-plans.json"),
-          pages: read.call("page-plans.json"),
-          flows: read.call("flow-plans.json")
+          pages:    read.call("page-plans.json"),
+          flows:    read.call("flow-plans.json"),
+          alters:   read.call("alter-plans.json")
         }
       )
     end
@@ -760,6 +808,14 @@ module MendixBridge
               status: 422
             )
           end
+          startup_error = ensure_local_database_available(project)
+          if startup_error
+            return json(
+              response,
+              { ok: false, message: startup_error },
+              status: 503
+            )
+          end
           [@mxcli, "sql", "-p", project, "--json", "--dsn", dsn, query]
         end
 
@@ -804,6 +860,78 @@ module MendixBridge
       "postgres://#{CGI.escape(user)}:#{CGI.escape(pass)}@#{host}:#{port}/#{name}?sslmode=disable"
     end
 
+    # SQL does not require the Mendix runtime. For a project-local database,
+    # start only its PostgreSQL Compose service on demand and keep it running
+    # between queries. External databases are contacted directly.
+    def ensure_local_database_available(project)
+      env_path = docker_env_path
+      return "No database connection configured." unless env_path
+
+      env = parse_env_file(env_path)
+      return nil if env["DB_MODE"].to_s == "external"
+
+      port = env.fetch("DB_PORT", "5432").to_i
+      return "Invalid local database port." unless port.positive?
+      docker_dir = File.dirname(env_path)
+      compose_path = File.join(docker_dir, "docker-compose.yml")
+      return "Local database definition is missing: #{compose_path}" unless File.file?(compose_path)
+      return nil if postgres_compose_ready?(docker_dir, env_path, compose_path, env)
+
+      @database_mutex.synchronize do
+        return nil if postgres_compose_ready?(docker_dir, env_path, compose_path, env)
+
+        output, error, status = Open3.capture3(
+          "docker", "compose",
+          "--env-file", env_path,
+          "-f", compose_path,
+          "up", "-d", "db",
+          chdir: docker_dir
+        )
+        unless status.success?
+          detail = clean_mxcli_error(error.empty? ? output : error)
+          return "Could not start the local PostgreSQL service: #{detail}"
+        end
+
+        begin
+          Timeout.timeout(30) do
+            sleep 0.25 until postgres_compose_ready?(docker_dir, env_path, compose_path, env)
+          end
+        rescue Timeout::Error
+          return "PostgreSQL was started but did not become ready on localhost:#{port} within 30 seconds."
+        end
+      end
+      nil
+    rescue Errno::ENOENT
+      "Docker is required to start the project-local PostgreSQL service."
+    rescue StandardError => error
+      "Could not prepare the local database: #{error.message}"
+    end
+
+    def tcp_reachable?(host, port)
+      Socket.tcp(host, port, connect_timeout: 0.25) { |socket| socket.close }
+      true
+    rescue SystemCallError, IOError
+      false
+    end
+
+    def postgres_compose_ready?(docker_dir, env_path, compose_path, env)
+      return false unless tcp_reachable?("127.0.0.1", env.fetch("DB_PORT", "5432").to_i)
+
+      _output, _error, status = Open3.capture3(
+        "docker", "compose",
+        "--env-file", env_path,
+        "-f", compose_path,
+        "exec", "-T", "db",
+        "pg_isready",
+        "-U", env.fetch("DB_USER", "mendix"),
+        "-d", env.fetch("DB_NAME", "mendix"),
+        chdir: docker_dir
+      )
+      status.success?
+    rescue Errno::ENOENT
+      false
+    end
+
     def parse_query_rows(stdout)
       out = stdout.to_s.strip
       return [] if out.empty?
@@ -903,6 +1031,95 @@ module MendixBridge
       json(response, { error: "invalid JSON payload" }, status: 400)
     end
 
+    # ---- ALTER PAGE / ALTER SNIPPET --------------------------------------
+    #
+    # GET  /api/alter?qn=Module.Page  — widget tree + names for the page
+    # POST /api/alter                 — apply operations, check & save draft
+    #
+    # POST body:
+    #   { "qn": "Module.Page",
+    #     "operations": [
+    #       { "op": "set", "widget": "btnSave",
+    #         "props": { "Caption": "Save & Close", "ButtonStyle": "Success" } },
+    #       { "op": "insert_after", "widget": "tbEmail",
+    #         "body": "textbox tbPhone (Label: 'Phone', Attribute: Phone)" },
+    #       { "op": "drop", "widgets": ["tbUnused"] },
+    #       { "op": "replace", "widget": "tbName",
+    #         "body": "textarea taName (Label: 'Name', Attribute: Name)" },
+    #       { "op": "set_layout", "layout": "Atlas_Core.Atlas_Sidebar_Full" },
+    #       { "op": "add_variable", "name": "counter",
+    #         "type": "Integer", "default": "0" },
+    #       { "op": "drop_variable", "name": "legacyVar" }
+    #     ]
+    #   }
+
+    def alter_route(request, response)
+      case request.request_method
+      when "GET"  then alter_info(request, response)
+      when "POST" then alter_apply(request, response)
+      else json(response, { error: "method not allowed" }, status: 405)
+      end
+    end
+
+    def alter_info(request, response)
+      qn = request.query["qn"].to_s
+      return json(response, { error: "qn required" }, status: 400) if qn.empty?
+
+      detail = page_detail(qn)
+      return json(response, { error: "unknown page '#{qn}'" }, status: 404) unless detail
+
+      widget_tree  = detail["widget_tree"] || []
+      widget_names = detail["widget_names"] || MdlParser.flat_widget_names(widget_tree)
+
+      json(response, {
+        qn:,
+        widget_tree:,
+        widget_names:,
+        layout: detail["layout"],
+        title: detail["title"]
+      })
+    end
+
+    def alter_apply(request, response)
+      payload    = JSON.parse(request.body.to_s)
+      qn         = payload.fetch("qn").to_s
+      operations = payload.fetch("operations")
+
+      detail = page_detail(qn)
+      return json(response, { error: "unknown page '#{qn}'" }, status: 404) unless detail
+
+      widget_tree  = detail["widget_tree"] || []
+      known_names  = detail["widget_names"] || MdlParser.flat_widget_names(widget_tree)
+
+      # Validate before generating MDL
+      errors = AlterPageBuilder.validate(operations, known_names: known_names)
+      if errors.any?
+        return json(response, { ok: false, errors: }, status: 422)
+      end
+
+      mdl = AlterPageBuilder.build(qn:, operations:, known_names: known_names)
+
+      ok, message = check_mdl(mdl)
+      persist_draft(
+        "alter-plans.json", qn,
+        "operations" => operations,
+        "mdl"        => mdl,
+        "valid"      => ok,
+        "message"    => message
+      )
+      json(
+        response,
+        { ok:, mdl:, message: ok ? "Page changes validated and saved." : message },
+        status: ok ? 200 : 422
+      )
+    rescue KeyError => e
+      json(response, { error: "missing parameter: #{e.key}" }, status: 400)
+    rescue JSON::ParserError
+      json(response, { error: "invalid JSON payload" }, status: 400)
+    rescue ArgumentError => e
+      json(response, { ok: false, errors: [e.message] }, status: 422)
+    end
+
     # ---- app run/stop/log ------------------------------------------------
 
     def app_route(request, response)
@@ -1394,6 +1611,141 @@ module MendixBridge
       end
     end
 
+    # ---- XAS proxy / interceptor -----------------------------------------
+    #
+    # When enabled, the bridge sits between the browser and the Mendix runtime,
+    # logging every /xas/ call so you can inspect actions, operationIds, and
+    # the data the client reads or writes. The runtime stays unmodified — all
+    # requests are forwarded transparently and the original response is returned
+    # verbatim. Enable with POST /api/xas/enable; browser/Studio Pro must then
+    # point at the bridge port instead of the Mendix runtime port.
+
+    def xas_proxy(request, response)
+      target_port = mendix_runtime_port
+      unless @xas_proxy_enabled && target_port
+        return json(
+          response,
+          { error: "XAS proxy not enabled — POST /api/xas/enable first" },
+          status: 503
+        )
+      end
+
+      body = request.body.to_s
+      payload = body.empty? ? {} : JSON.parse(body)
+      action       = payload["action"].to_s
+      operation_id = payload.dig("params", "operationId").to_s
+
+      uri = URI("http://127.0.0.1:#{target_port}/xas/")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.read_timeout = 30
+
+      proxy_req = Net::HTTP::Post.new(uri.path)
+      %w[cookie x-csrf-token content-type].each do |h|
+        proxy_req[h] = request[h] if request[h]
+      end
+      proxy_req.body = body
+
+      proxy_res  = http.request(proxy_req)
+      res_body   = proxy_res.body.to_s
+      res_status = proxy_res.code.to_i
+
+      entry = {
+        "at"            => Time.now.iso8601,
+        "action"        => action,
+        "operation_id"  => operation_id.empty? ? nil : operation_id,
+        "params"        => payload["params"],
+        "status"        => res_status,
+        "response_size" => res_body.bytesize
+      }
+      if res_body.bytesize < 16_384
+        begin
+          entry["response"] = JSON.parse(res_body)
+        rescue JSON::ParserError
+          nil
+        end
+      end
+
+      @xas_mutex.synchronize do
+        @xas_log << entry
+        @xas_log = @xas_log.last(500)
+      end
+
+      response.status = res_status
+      response["content-type"] = proxy_res["content-type"] || "application/json"
+      response["cache-control"] = "no-store"
+      response.body = res_body
+    rescue JSON::ParserError
+      json(response, { error: "invalid JSON in request body" }, status: 400)
+    rescue Errno::ECONNREFUSED
+      json(response, { error: "Mendix runtime not reachable on port #{target_port}" }, status: 502)
+    rescue Net::ReadTimeout
+      json(response, { error: "Mendix runtime timed out" }, status: 504)
+    end
+
+    # GET  /api/xas/log     — query the intercepted call log
+    # GET  /api/xas/status  — proxy enabled state + log size
+    # POST /api/xas/enable  — start proxying (optional body: {"port": 8080})
+    # POST /api/xas/disable — stop proxying
+    # POST /api/xas/clear   — wipe the log
+    def xas_control(request, response)
+      action = request.path.delete_prefix("/api/xas").sub(%r{\A/}, "")
+
+      case [request.request_method, action]
+      when ["GET", "log"]
+        limit = request.query["limit"].to_s.empty? ? 50 : [[request.query["limit"].to_i, 1].max, 500].min
+        entries = @xas_mutex.synchronize { @xas_log.dup }
+        entries = entries.select { |e| e["action"] == request.query["action"] } if request.query["action"].to_s != ""
+        entries = entries.select { |e| e["at"] >= request.query["since"] }      if request.query["since"].to_s != ""
+        json(response, { entries: entries.last(limit), total: @xas_log.size })
+
+      when ["GET", "status"]
+        json(response, {
+          enabled:     @xas_proxy_enabled,
+          target_port: @xas_target_port || mendix_runtime_port,
+          log_size:    @xas_mutex.synchronize { @xas_log.size }
+        })
+
+      when ["POST", "enable"]
+        payload = request.body.to_s.empty? ? {} : JSON.parse(request.body.to_s)
+        port = payload["port"]&.to_i.then { |p| p&.positive? ? p : nil } || mendix_runtime_port
+        unless port
+          return json(
+            response,
+            { ok: false, message: "Cannot determine Mendix runtime port. Pass {\"port\": 8080} or set APP_PORT in .docker/.env." },
+            status: 422
+          )
+        end
+        @xas_target_port   = port
+        @xas_proxy_enabled = true
+        json(response, { ok: true, message: "XAS proxy enabled → port #{port}. Point your browser at http://localhost:#{@port} instead of :#{port}." })
+
+      when ["POST", "disable"]
+        @xas_proxy_enabled = false
+        json(response, { ok: true, message: "XAS proxy disabled." })
+
+      when ["POST", "clear"]
+        @xas_mutex.synchronize { @xas_log.clear }
+        json(response, { ok: true, message: "XAS log cleared." })
+
+      else
+        json(response, { error: "not found" }, status: 404)
+      end
+    rescue JSON::ParserError
+      json(response, { error: "invalid JSON payload" }, status: 400)
+    end
+
+    # Resolves the Mendix runtime port: explicit override > .docker/.env APP_PORT > 8080.
+    def mendix_runtime_port
+      return @xas_target_port if @xas_target_port
+
+      path = docker_env_path
+      return 8080 unless path
+
+      env  = parse_env_file(path)
+      port = env["APP_PORT"].to_i
+      port.positive? ? port : 8080
+    end
+
     def json(response, payload, status: 200)
       response.status = status
       response["content-type"] = "application/json; charset=utf-8"