mxrb 0.1.0

data/bin/mxrb

@@ -0,0 +1,1613 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/mxrb"
+require "shellwords"
+require "io/console"
+
+# rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+def render_plan_report(report, json:)
+  payload = {
+    engine: report.engine, analyzed: report.analyzed, total_cost: report.total_cost,
+    planning_time_ms: report.planning_time_ms, execution_time_ms: report.execution_time_ms,
+    clean: report.clean?, findings: report.findings.map(&:to_h)
+  }
+  return puts(JSON.pretty_generate(payload)) if json
+
+  puts "Engine         : #{report.engine}"
+  puts "Mode           : #{report.analyzed ? 'actual' : 'estimated'}"
+  puts "Total cost     : #{report.total_cost}"
+  report.findings.each do |finding|
+    puts "[#{finding.severity.to_s.upcase}] #{finding.rule}: #{finding.relation || finding.node_type}"
+    puts "  #{finding.message}"
+    puts "  #{finding.suggestion}"
+  end
+  puts "[mxrb] No plan findings" if report.findings.empty?
+end
+# rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+# rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+def render_workload_report(report, json:)
+  payload = {
+    engine: report.engine, clean: report.clean?,
+    queries: report.queries.map(&:to_h), table_stats: report.table_stats,
+    index_stats: report.index_stats, findings: report.findings.map(&:to_h)
+  }
+  return puts(JSON.pretty_generate(payload)) if json
+
+  report.queries.each do |query|
+    puts "#{query.query_id}\t#{query.calls} calls\t#{query.total_time_ms.round(3)} ms total\t" \
+         "#{query.mean_time_ms.round(3)} ms mean"
+  end
+  report.findings.each do |finding|
+    puts "[#{finding.severity.to_s.upcase}] #{finding.rule}: #{finding.subject}"
+    puts "  #{finding.message}"
+    puts "  #{finding.suggestion}"
+  end
+  puts "[mxrb] No workload findings" if report.findings.empty?
+end
+# rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+def render_index_advice(advice, json:) # rubocop:disable Metrics/AbcSize
+  payload = {
+    candidates: advice.candidates.map(&:to_h), redundant_indexes: advice.redundant_indexes
+  }
+  return puts(JSON.pretty_generate(payload)) if json
+
+  advice.candidates.each do |candidate|
+    puts "[#{candidate.confidence.to_s.upcase}] #{candidate.relation}(#{candidate.columns.join(', ')})"
+    puts "  #{candidate.reason} Queries: #{candidate.query_ids.join(', ')}"
+  end
+  advice.redundant_indexes.each { puts "[WARNING] overlapping indexes: #{_1.join(' and ')}" }
+  puts '[mxrb] No evidence-backed index candidates' if advice.candidates.empty?
+end
+
+SCAFFOLD_COMMANDS = (Mxrb::Scaffold::Help::COMMANDS.keys - ["design"]).freeze
+
+command = ARGV.shift
+
+case command
+when 'doctor'
+  json = ARGV.delete('--json')
+  root = ARGV.shift || Dir.pwd
+  report = Mxrb::Doctor.new(root).run
+  if json
+    puts JSON.pretty_generate(root: report.root, valid: report.valid?, checks: report.checks.map(&:to_h))
+  else
+    report.checks.each { puts "[#{_1.status.to_s.upcase}] #{_1.name}: #{_1.message}" }
+    puts "[mxrb] #{report.errors.size} error(s), #{report.warnings.size} warning(s)"
+  end
+  exit 1 unless report.valid?
+
+when 'benchmark'
+  path = ARGV.shift or abort 'Usage: mxrb benchmark <file.mpr> [--iterations N] [--json]'
+  index = ARGV.index('--iterations')
+  iterations = index ? ARGV.slice!(index, 2).last : 3
+  abort '--iterations requires a value' if index && iterations.nil?
+  json = ARGV.delete('--json')
+  result = Mxrb::Benchmark.new(path, iterations:).run
+  if json
+    puts JSON.pretty_generate(result.to_h)
+  else
+    puts "Units            : #{result.units}"
+    puts "Open average     : #{result.open_seconds}s"
+    puts "Index average    : #{result.index_seconds}s"
+    puts "Validate average : #{result.validate_seconds}s"
+  end
+
+when 'project'
+  action = ARGV.shift or abort 'Usage: mxrb project inspect [DIR] [--json]'
+  abort "Unknown project action #{action.inspect}" unless action == 'inspect'
+  json = ARGV.delete('--json')
+  payload = Mxrb::ProjectLifecycle.new(ARGV.shift || Dir.pwd).inspect
+  if json
+    puts JSON.pretty_generate(payload)
+  else
+    payload.each { |key, value| puts "#{key}: #{Array(value).join(', ')}" }
+  end
+
+when 'upgrade'
+  version_index = ARGV.index('--mendix')
+  abort 'Usage: mxrb upgrade --mendix VERSION [--target DIR] [--apply]' unless version_index
+  version = ARGV.slice!(version_index, 2).last
+  abort '--mendix requires a value' unless version
+  target_index = ARGV.index('--target')
+  target = target_index ? ARGV.slice!(target_index, 2).last : Dir.pwd
+  abort '--target requires a value' if target_index && target.nil?
+  apply = ARGV.delete('--apply') ? true : false
+  result = Mxrb::ProjectLifecycle.new(target).upgrade(version, apply:)
+  puts "[mxrb] #{apply ? 'Updated' : 'Preview'} #{result.path}: #{result.from} -> #{result.to}"
+
+when 'migrate'
+  action = ARGV.shift or abort 'Usage: mxrb migrate <check|plan> [DIR] [--json]'
+  json = ARGV.delete('--json')
+  result = Mxrb::ProjectLifecycle.new(ARGV.shift || Dir.pwd).migration_plan
+  payload = {
+    clean: result.clean?, added: result.diff.added.map(&:to_h),
+    removed: result.diff.removed.map(&:to_h), changed: result.diff.changed.map(&:to_h)
+  }
+  if json
+    puts JSON.pretty_generate(payload)
+  else
+    puts "Added: #{payload[:added].size}"
+    puts "Removed: #{payload[:removed].size}"
+    puts "Changed: #{payload[:changed].size}"
+    puts "[mxrb] #{result.clean? ? 'No model drift' : 'Model drift detected'}"
+  end
+  exit 1 if action == 'check' && !result.clean?
+  abort "Unknown migrate action #{action.inspect}" unless %w[check plan].include?(action)
+
+when "inspect"
+  path = ARGV.shift or abort "Usage: mxrb inspect <file.mpr>"
+  Mxrb.open(path) do |p|
+    puts "Project : #{p.name}"
+    puts "Version : #{p.mendix_version}"
+    puts "Tables  : #{p.tables.join(', ')}"
+    puts ""
+    puts "Unit types found:"
+    p.all_units.filter_map { p.parse_bson(_1)["$Type"] }.sort.uniq.each { puts "  #{_1}" }
+    puts ""
+    puts "All units:"
+    p.all_units.each do |u|
+      type = p.parse_bson(u)["$Type"]
+      puts "  [#{u['UnitID']}] #{type} (container=#{u['ContainerID']}, name=#{u['ContainmentName']})"
+    end
+  end
+
+when "dump-unit"
+  path = ARGV.shift or abort "Usage: mxrb dump-unit <file.mpr> <unit_id>"
+  id   = ARGV.shift or abort "Usage: mxrb dump-unit <file.mpr> <unit_id>"
+  Mxrb.open(path) do |p|
+    u = p.raw_unit(id)
+    abort "Unit #{id} not found" unless u
+    puts "UnitID           : #{u['UnitID']}"
+    puts "ContainerID      : #{u['ContainerID']}"
+    puts "ContainmentName  : #{u['ContainmentName']}"
+    puts "TypeName         : #{p.parse_bson(u)['$Type']}"
+    puts "ContentsHash     : #{u['ContentsHash']}"
+    puts "Contents (hex)   :"
+    blob = p.mpr.content_bytes(u)
+    if blob
+      blob.b.bytes.each_slice(16).with_index do |row, i|
+        hex  = row.map { "%02x" % _1 }.join(" ")
+        asc  = row.map { _1.between?(32, 126) ? _1.chr : "." }.join
+        printf "  %04x  %-48s  %s\n", i * 16, hex, asc
+      end
+    else
+      puts "  (empty)"
+    end
+  end
+
+when "sql"
+  path = ARGV.shift or abort "Usage: mxrb sql <file.mpr> \"SELECT ...\""
+  sql  = ARGV.shift or abort "Usage: mxrb sql <file.mpr> \"SELECT ...\""
+  Mxrb.open(path) do |p|
+    rows = p.query(sql)
+    rows.each { puts _1.inspect }
+    puts "(#{rows.size} rows)"
+  end
+
+when "modules"
+  path = ARGV.shift or abort "Usage: mxrb modules <file.mpr>"
+  Mxrb.open(path) do |p|
+    p.modules.each { puts _1.inspect }
+  end
+
+when "protocols"
+  path = ARGV.shift or abort "Usage: mxrb protocols <file.mpr> [--json]"
+  json = ARGV.delete("--json")
+  Mxrb.open(path) do |project|
+    audit = Mxrb::Protocols.audit(project)
+    unknown = audit.unknown_marketplace_modules
+    if json
+      puts JSON.generate(
+        connectors: audit.connectors.map(&:to_h),
+        unknown_marketplace_modules: unknown,
+        project: File.basename(path)
+      )
+    else
+      if audit.connectors.empty?
+        puts "No known protocol connectors found."
+      else
+        audit.connectors.each do |connector|
+          puts "#{connector.protocol}\t#{connector.module_name}\t" \
+               "marketplace=#{connector.metadata[:marketplace_id]}\tprotected=#{connector.protected}"
+          puts "  entities: #{connector.entities.join(', ')}" unless connector.entities.empty?
+          puts "  microflows: #{connector.microflows.join(', ')}" unless connector.microflows.empty?
+        end
+      end
+      unless unknown.empty?
+        puts "Unrecognized marketplace modules (#{unknown.size}): #{unknown.join(', ')}"
+        puts "Run `mxrb modules #{path}` to list every module."
+      end
+    end
+  end
+
+when "generate"
+  source = ARGV.shift or abort "Usage: mxrb generate <definition.rb> [file.mpr]"
+  target = ARGV.shift
+  abort "#{source}: file not found" unless File.file?(source)
+  if target
+    ENV["MXRB_OUTPUT_PATH"] = File.expand_path(target)
+  end
+  load File.expand_path(source)
+  puts "[mxrb] Generated #{target || 'project from definition'}"
+
+when "widgets"
+  widgets_usage = <<~USAGE
+    Usage: mxrb widgets sync <definition.rb> <file.mpr>
+
+    Generate the project, load schemas from .mpk files in widgets/, and
+    regenerate Data Grid 2, Combo Box, and other pluggable widget properties.
+  USAGE
+  action = ARGV.shift
+  if action.nil? || %w[-h --help help].include?(action)
+    puts widgets_usage
+    exit(action.nil? ? 1 : 0)
+  end
+  abort "Unknown widgets action #{action.inspect}; use sync" unless action == "sync"
+  if %w[-h --help].include?(ARGV.first)
+    puts widgets_usage
+    exit 0
+  end
+  source = ARGV.shift or abort "Usage: mxrb widgets sync <definition.rb> <file.mpr>"
+  target = ARGV.shift or abort "Usage: mxrb widgets sync <definition.rb> <file.mpr>"
+  result = Mxrb::WidgetSynchronizer.new(source, target).sync!
+  puts "[mxrb] Synchronized widget schemas with #{result.mx_path}"
+  puts "[mxrb] Generated #{result.project}"
+
+when "frontend"
+  frontend_usage = <<~USAGE
+    Usage: mxrb frontend migrate FILE.mpr [--apply] [--json]
+
+    Preview frontend widget, layout-row, and design-property migrations.
+    The MPR is changed only when --apply is provided and the plan is safe.
+  USAGE
+  action = ARGV.shift
+  if action.nil? || %w[-h --help help].include?(action)
+    puts frontend_usage
+    exit(action.nil? ? 1 : 0)
+  end
+  abort "Unknown frontend action #{action.inspect}; use migrate" unless action == "migrate"
+  if %w[-h --help].include?(ARGV.first)
+    puts frontend_usage
+    exit 0
+  end
+  path = ARGV.shift or abort "Usage: mxrb frontend migrate FILE.mpr [--apply] [--json]"
+  apply = !ARGV.delete("--apply").nil?
+  json = !ARGV.delete("--json").nil?
+  abort "Unknown arguments: #{ARGV.join(' ')}" unless ARGV.empty?
+  plan = Mxrb::Frontend::Migrator.plan(path)
+  plan.apply! if apply && plan.safe?
+  payload = {
+    version: plan.version, changes: plan.changes.size, widgets: plan.widgets,
+    layout_rows: plan.layout_rows, design_properties: plan.design_properties,
+    issues: plan.issues.map(&:to_h), safe: plan.safe?, applied: plan.applied?
+  }
+  if json
+    puts JSON.pretty_generate(payload)
+  else
+    puts "Version           : #{payload[:version]}"
+    puts "Changes           : #{payload[:changes]}"
+    puts "Widgets           : #{payload[:widgets]}"
+    puts "Layout rows       : #{payload[:layout_rows]}"
+    puts "Design properties : #{payload[:design_properties]}"
+    puts "Safe              : #{payload[:safe]}"
+    puts "Applied           : #{payload[:applied]}"
+    plan.issues.each do |issue|
+      puts "[#{issue.kind.to_s.upcase}] #{issue.unit_id}#{issue.path}: #{issue.message}"
+    end
+  end
+  exit 1 unless plan.safe?
+
+when "export"
+  source = ARGV.shift or abort "Usage: mxrb export <file.mpr> <ruby-project-dir>"
+  output = ARGV.shift or abort "Usage: mxrb export <file.mpr> <ruby-project-dir>"
+  destination = Mxrb::Exporter.new(source, output).export!
+  puts "[mxrb] Exported Ruby project to #{destination}"
+
+when "validate"
+  path = ARGV.shift or abort "Usage: mxrb validate <file.mpr>"
+  result = Mxrb.validate(path)
+  result.warnings.each { warn "[mxrb] warning: #{_1}" }
+  if result.valid?
+    puts "[mxrb] OK"
+  else
+    result.errors.each { warn "[mxrb] error: #{_1}" }
+    exit 1
+  end
+
+when "preflight"
+  path = ARGV.shift or abort "Usage: mxrb preflight <file.mpr> [--json]"
+  json = ARGV.delete("--json")
+  abort "Unknown arguments: #{ARGV.join(' ')}" unless ARGV.empty?
+  report = Mxrb.compatibility(path)
+  if json
+    puts JSON.pretty_generate(report.to_h)
+  else
+    puts "Project : #{report.path}"
+    puts "Mendix  : #{report.mendix_version}"
+    puts "Units   : #{report.stats[:units]}"
+    report.findings.each do |finding|
+      puts "[#{finding.severity.to_s.upcase}] #{finding.category} #{finding.type} " \
+           "at #{finding.location}: #{finding.message}"
+    end
+    puts "[mxrb] #{report.errors.size} error(s), #{report.warnings.size} warning(s)"
+  end
+  exit 1 unless report.compatible?
+
+when "pack"
+  path = ARGV.shift or abort "Usage: mxrb pack <file.mpr> --output FILE.mda [--deployment DIR] [--force]"
+  option = lambda do |name|
+    index = ARGV.index(name)
+    next unless index
+
+    abort "#{name} requires a value" unless ARGV[index + 1]
+    ARGV.slice!(index, 2).last
+  end
+  output = option.call("--output") || File.join(
+    File.dirname(File.expand_path(path)), "build", "#{File.basename(path, '.mpr')}.mda"
+  )
+  deployment = option.call("--deployment")
+  force = ARGV.delete("--force") ? true : false
+  abort "Unknown arguments: #{ARGV.join(' ')}" unless ARGV.empty?
+  result = Mxrb::Compiler::Packager.new(path, deployment:).pack(output:, force:)
+  puts "[mxrb] Packed #{result.files} files for Mendix #{result.mendix_version}"
+  puts "[mxrb] SHA-256 #{result.sha256}"
+  puts "[mxrb] #{result.path}"
+
+when "portable"
+  path = ARGV.shift or abort "Usage: mxrb portable <file.mpr> --output runtime.zip [options]"
+  option = lambda do |name|
+    index = ARGV.index(name)
+    next unless index
+
+    abort "#{name} requires a value" unless ARGV[index + 1]
+    ARGV.slice!(index, 2).last
+  end
+  output = option.call("--output") || File.join(
+    File.dirname(File.expand_path(path)), "build", "runtime.zip"
+  )
+  deployment = option.call("--deployment")
+  mendix_home = option.call("--mendix-home")
+  force = ARGV.delete("--force") ? true : false
+  abort "Unknown arguments: #{ARGV.join(' ')}" unless ARGV.empty?
+  result = Mxrb::Compiler::PortablePackager.new(
+    path, deployment:, mendix_home:
+  ).pack(output:, force:)
+  puts "[mxrb] Packed portable Runtime with #{result.files} files for Mendix #{result.mendix_version}"
+  puts "[mxrb] SHA-256 #{result.sha256}"
+  puts "[mxrb] #{result.path}"
+
+when "mda"
+  action = ARGV.shift or abort "Usage: mxrb mda <inspect|compare> ..."
+  case action
+  when "inspect"
+    path = ARGV.shift or abort "Usage: mxrb mda inspect <file.mda> [--json]"
+    json = ARGV.delete("--json")
+    abort "Unknown arguments: #{ARGV.join(' ')}" unless ARGV.empty?
+    result = Mxrb::Compiler::Mda.inspect(path)
+    if json
+      puts JSON.pretty_generate(
+        path: result.path, sha256: result.sha256, roots: result.roots,
+        files: result.files.size, metadata: result.metadata
+      )
+    else
+      puts "Runtime       : #{result.metadata['RuntimeVersion']}"
+      puts "Project       : #{result.metadata['ProjectName']}"
+      puts "Files         : #{result.files.size}"
+      puts "Roots         : #{result.roots.join(', ')}"
+      puts "SHA-256       : #{result.sha256}"
+    end
+  when "compare"
+    left = ARGV.shift or abort "Usage: mxrb mda compare <left.mda> <right.mda>"
+    right = ARGV.shift or abort "Usage: mxrb mda compare <left.mda> <right.mda>"
+    differences = Mxrb::Compiler::Mda.compare(left, right)
+    differences.each { puts "#{_1.status}\t#{_1.path}" }
+    puts "[mxrb] #{differences.size} difference(s)"
+  else
+    abort "Unknown mda action #{action.inspect}; use inspect or compare"
+  end
+
+when "compare"
+  left = ARGV.shift or abort "Usage: mxrb compare <left.mpr> <right.mpr>"
+  right = ARGV.shift or abort "Usage: mxrb compare <left.mpr> <right.mpr>"
+  result = Mxrb.compare(left, right)
+  if result.identical?
+    puts "[mxrb] OK"
+  else
+    result.differences.each { puts "[mxrb] diff: #{_1}" }
+    exit 1
+  end
+
+when "diff"
+  left = ARGV.shift or abort "Usage: mxrb diff <left.mpr> <right.mpr>"
+  right = ARGV.shift or abort "Usage: mxrb diff <left.mpr> <right.mpr>"
+  result = Mxrb.diff(left, right)
+  result.changes.each do |change|
+    puts "#{change.operation}\t#{change.path.join('.')}\t" \
+         "#{change.before.inspect}\t=>\t#{change.after.inspect}"
+  end
+  exit 1 unless result.identical?
+
+when "refs", "callers", "callees", "impact"
+  path = ARGV.shift or abort "Usage: mxrb #{command} <file.mpr> <qualified-name>"
+  name = ARGV.shift or abort "Usage: mxrb #{command} <file.mpr> <qualified-name>"
+  begin
+    Mxrb.open(path) do |project|
+      case command
+      when "refs"
+        project.references_to(name).each do |reference|
+          puts [
+            reference.source.qualified_name,
+            reference.source.kind,
+            reference.relation,
+            reference.path.join(".")
+          ].join("\t")
+        end
+      when "callers"
+        project.callers_of(name).each do |artifact|
+          puts "#{artifact.qualified_name}\t#{artifact.kind}"
+        end
+      when "callees"
+        project.callees_of(name).each do |artifact|
+          puts "#{artifact.qualified_name}\t#{artifact.kind}"
+        end
+      when "impact"
+        project.impact_of(name).artifacts.each do |artifact|
+          puts "#{artifact.qualified_name}\t#{artifact.kind}"
+        end
+      end
+    end
+  rescue KeyError, ArgumentError => e
+    warn "[mxrb] error: #{e.message}"
+    exit 1
+  end
+
+when "rename"
+  path = ARGV.shift or abort "Usage: mxrb rename <file.mpr> <old-name> <new-name> [--apply]"
+  old_name = ARGV.shift or abort "Usage: mxrb rename <file.mpr> <old-name> <new-name> [--apply]"
+  new_name = ARGV.shift or abort "Usage: mxrb rename <file.mpr> <old-name> <new-name> [--apply]"
+  apply = ARGV.delete("--apply")
+  begin
+    plan = Mxrb.open(path, readonly: !apply) do |project|
+      project.plan_rename(old_name, to: new_name).tap { _1.apply! if apply }
+    end
+  rescue KeyError, ArgumentError => e
+    warn "[mxrb] error: #{e.message}"
+    exit 1
+  end
+  plan.changes.each do |change|
+    puts [
+      change.unit_id,
+      change.path.join("."),
+      change.before.inspect,
+      "=>",
+      change.after.inspect
+    ].join("\t")
+  end
+  puts "[mxrb] #{apply ? 'Renamed' : 'Preview'}: #{plan.changes.size} changes " \
+       "in #{plan.affected_units.size} units"
+
+when "remove"
+  path = ARGV.shift or abort "Usage: mxrb remove <file.mpr> <qualified-name> [--apply]"
+  name = ARGV.shift or abort "Usage: mxrb remove <file.mpr> <qualified-name> [--apply]"
+  apply = ARGV.delete("--apply")
+  begin
+    plan = Mxrb.open(path, readonly: !apply) do |project|
+      project.plan_remove(name).tap { _1.apply! if apply }
+    end
+  rescue KeyError, ArgumentError => e
+    warn "[mxrb] error: #{e.message}"
+    exit 1
+  end
+  puts "Artifact            : #{plan.artifact.qualified_name} (#{plan.artifact.kind})"
+  puts "Incoming references : #{plan.incoming.size}"
+  plan.incoming.each { puts "  #{_1.source.qualified_name}\t#{_1.relation}" }
+  puts "Child units         : #{plan.children.size}"
+  puts "[mxrb] #{apply ? 'Removed' : plan.safe? ? 'Safe removal preview' : 'Blocked removal'}"
+  exit 1 unless plan.safe?
+
+when "move"
+  path = ARGV.shift or abort "Usage: mxrb move <file.mpr> <name> <container> [--apply]"
+  name = ARGV.shift or abort "Usage: mxrb move <file.mpr> <name> <container> [--apply]"
+  container = ARGV.shift or abort "Usage: mxrb move <file.mpr> <name> <container> [--apply]"
+  apply = ARGV.delete("--apply")
+  begin
+    plan = Mxrb.open(path, readonly: !apply) do |project|
+      project.plan_move(name, to: container).tap { _1.apply! if apply }
+    end
+  rescue KeyError, ArgumentError => e
+    warn "[mxrb] error: #{e.message}"
+    exit 1
+  end
+  puts "Artifact  : #{plan.source.qualified_name} (#{plan.source.kind})"
+  puts "Container : #{plan.before_container} -> #{plan.after_container}"
+  puts "[mxrb] #{apply ? 'Moved' : plan.empty? ? 'Already in container' : 'Move preview'}"
+
+when "lint", "report"
+  path = ARGV.shift or abort "Usage: mxrb #{command} <file.mpr>"
+  report = Mxrb.open(path, &:analyze)
+  if command == "lint"
+    report.diagnostics.each do |diagnostic|
+      puts "[#{diagnostic.severity}] #{diagnostic.rule}: #{diagnostic.message}"
+    end
+  else
+    puts "Artifacts not referenced : #{report.unreferenced.size}"
+    puts "Unresolved references     : #{report.unresolved_references.size}"
+    puts "Call cycles              : #{report.call_cycles.size}"
+    puts "Cross-module dependencies: #{report.module_dependencies.size}"
+    report.module_dependencies.each do |dependency|
+      puts [
+        dependency.from,
+        "->",
+        dependency.to,
+        "#{dependency.references.size} references",
+        "#{dependency.source_artifacts.size} artifacts"
+      ].join("\t")
+    end
+  end
+  puts "[mxrb] #{report.errors.size} errors, #{report.warnings.size} warnings"
+  exit 1 unless report.valid?
+
+when "cache"
+  action = ARGV.shift or abort "Usage: mxrb cache <status|warm|clear> <file.mpr> [--json]"
+  path = ARGV.shift or abort "Usage: mxrb cache <status|warm|clear> <file.mpr> [--json]"
+  json = ARGV.delete("--json")
+  readonly = action == "status"
+  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  result = Mxrb.open(path, readonly:) do |project|
+    case action
+    when "status"
+      project.semantic_cache_info
+    when "warm"
+      project.warm_semantic_cache!
+    when "clear"
+      removed = project.clear_semantic_cache!
+      project.semantic_cache_info.merge(removed:)
+    else
+      abort "Unknown cache action #{action.inspect}; use status, warm or clear"
+    end
+  end
+  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+  payload = result.merge(elapsed_seconds: elapsed.round(6))
+  if json
+    puts JSON.pretty_generate(payload)
+  else
+    puts "Present     : #{payload[:present]}"
+    puts "Current hit : #{payload[:hit]}"
+    puts "Entries     : #{payload[:entries]}"
+    puts "Bytes       : #{payload[:bytes]}"
+    puts "Fingerprint : #{payload[:current_fingerprint] || '(unavailable)'}"
+    puts "Removed     : #{payload[:removed]}" if payload.key?(:removed)
+    puts "Elapsed     : #{format('%.6f', payload[:elapsed_seconds])}s"
+  end
+
+when "oql"
+  path = ARGV.shift or abort "Usage: mxrb oql <file.mpr> [--dialect ansi|postgresql|sql_server] [--json]"
+  json = ARGV.delete("--json")
+  dialect_index = ARGV.index("--dialect")
+  dialect = if dialect_index
+              abort "--dialect requires a value" unless ARGV[dialect_index + 1]
+              ARGV.slice!(dialect_index, 2).last.to_sym
+            else
+              :postgresql
+            end
+  begin
+    views = Mxrb.open(path) { _1.oql_sql_views(dialect:) }
+  rescue ArgumentError => e
+    abort "[mxrb] error: #{e.message}"
+  end
+  if json
+    puts JSON.pretty_generate(
+      views.map do |view|
+        {
+          name: view.query.qualified_name, kind: view.query.kind, oql: view.query.oql,
+          sql: view.sql, dialect: view.dialect, confidence: view.confidence,
+          parameters: view.parameters, warnings: view.warnings
+        }
+      end
+    )
+  elsif views.empty?
+    puts "[mxrb] No native OQL found"
+  else
+    views.each_with_index do |view, index|
+      puts "" unless index.zero?
+      puts "#{view.query.qualified_name} (#{view.query.kind})"
+      puts "OQL:"
+      puts view.query.oql
+      puts "SQL (#{view.dialect}, #{view.confidence}):"
+      puts(view.sql || "(not generated)")
+      view.warnings.each { warn "[mxrb] warning: #{_1}" }
+    end
+  end
+
+when "analyze"
+  option = lambda do |name|
+    index = ARGV.index(name)
+    next unless index
+
+    abort "#{name} requires a value" unless ARGV[index + 1]
+    ARGV.slice!(index, 2).last
+  end
+  dialect = (option.call("--dialect") || "postgresql").to_sym
+  sql_source = option.call("--sql")
+  oql_source = option.call("--oql")
+  abort "Use only one of --sql or --oql" if sql_source && oql_source
+  json = ARGV.delete("--json")
+  begin
+    analyzer = Mxrb::Oql::Analyzer.new(dialect:)
+    reports = if sql_source
+                [analyzer.analyze_sql(sql_source)]
+              elsif oql_source
+                [analyzer.analyze_source(oql_source)]
+              else
+                path = ARGV.shift or
+                  abort "Usage: mxrb analyze <file.mpr> [--dialect DIALECT] [--json]"
+                Mxrb.open(path) { _1.oql_analysis(dialect:) }
+              end
+  rescue ArgumentError => e
+    abort "[mxrb] error: #{e.message}"
+  end
+  payload = reports.map do |report|
+    {
+      name: report.query.qualified_name, kind: report.query.kind, source: report.query.oql,
+      clean: report.clean?, warnings: report.warnings?,
+      findings: report.findings.map do |finding|
+        {
+          rule: finding.rule, severity: finding.severity, fragment: finding.fragment,
+          message: finding.message, suggestions: finding.suggestions,
+          selected_suggestion: finding.suggestions[dialect]
+        }
+      end
+    }
+  end
+  if json
+    puts JSON.pretty_generate(payload)
+  elsif payload.all? { _1[:findings].empty? }
+    puts "[mxrb] No analysis findings"
+  else
+    dialect_name = { postgresql: "PostgreSQL", sql_server: "SQL Server", ansi: "ANSI" }
+    reports.each do |report|
+      report.for_dialect(dialect).each do |finding, suggestion|
+        puts "#{report.query.qualified_name}  [#{finding.severity.to_s.upcase}] #{finding.rule}"
+        puts "  #{report.query.kind.to_s.upcase}: #{finding.fragment}"
+        puts "  #{finding.message}"
+        puts "  #{dialect_name.fetch(dialect)} -> #{suggestion}"
+      end
+    end
+  end
+
+when "design"
+  action = ARGV.shift or abort "Usage: mxrb design <scan|migrate> ..."
+  if ["init", "--help"].include?(action)
+    ARGV.unshift(action)
+    Mxrb::Scaffold::CLI.new("design", ARGV).run
+    exit 0
+  end
+  path = ARGV.shift or abort "Usage: mxrb design #{action} <file.mpr> ..."
+  json = ARGV.delete("--json")
+  case action
+  when "scan"
+    design = Mxrb.open(path, &:design_system)
+    payload = {
+      tokens: design.tokens.map do |token|
+        {
+          name: token.name, value: token.value, kind: token.kind, theme: token.theme,
+          path: token.path, line: token.line
+        }
+      end,
+      themes: design.themes, catalogs: design.catalogs,
+      unresolved_references: design.unresolved_references.map do |entry|
+        { token: entry[:token].name, reference: entry[:reference] }
+      end,
+      literal_colors: design.literal_colors.map(&:name)
+    }
+    if json
+      puts JSON.pretty_generate(payload)
+    else
+      puts "name\tvalue\tkind\ttheme\tlocation"
+      design.tokens.each do |token|
+        puts [
+          token.name, token.value, token.kind, token.theme || "-", "#{token.path}:#{token.line}"
+        ].join("\t")
+      end
+      puts "[mxrb] #{design.tokens.size} tokens, #{design.themes.size} themes, " \
+           "#{design.literal_colors.size} literal colors, " \
+           "#{design.unresolved_references.size} unresolved references"
+    end
+  when "migrate"
+    literal = ARGV.shift or
+      abort "Usage: mxrb design migrate <file.mpr> <literal> <token> [--apply] [--json]"
+    token = ARGV.shift or
+      abort "Usage: mxrb design migrate <file.mpr> <literal> <token> [--apply] [--json]"
+    apply = ARGV.delete("--apply")
+    plan = Mxrb.open(path) { _1.plan_design_token_migration(literal => token) }
+    plan.apply! if apply
+    payload = {
+      applied: plan.applied?,
+      changes: plan.changes.map { { path: _1.path, occurrences: _1.occurrences } },
+      occurrences: plan.changes.sum(&:occurrences)
+    }
+    if json
+      puts JSON.pretty_generate(payload)
+    else
+      plan.changes.each { puts "#{_1.path}\t#{_1.occurrences} replacements" }
+      label = apply ? "Applied" : "Preview" # rubocop:disable Metrics/BlockNesting
+      puts "[mxrb] #{label}: #{payload[:occurrences]} replacements in #{plan.changes.size} files"
+    end
+  else
+    abort "Unknown design action #{action.inspect}; use scan or migrate"
+  end
+
+when "db"
+  action = ARGV.shift or
+    abort "Usage: mxrb db <up|sync|down|destroy|status|url|sql|explain|workload|indexes|shell> <file.mpr>"
+  path = ARGV.shift or abort "Usage: mxrb db #{action} <file.mpr>"
+  option = lambda do |name, fallback = nil|
+    index = ARGV.index(name)
+    next fallback unless index
+
+    abort "#{name} requires a value" unless ARGV[index + 1]
+    ARGV.slice!(index, 2).last
+  end
+  engine = option.call("--engine", "postgresql").to_sym
+  port_index = ARGV.index("--port")
+  port = if port_index
+           abort "--port requires a value" unless ARGV[port_index + 1]
+           ARGV.slice!(port_index, 2).last
+         else
+           55_432
+         end
+  runtime_port = option.call("--runtime-port", 18_080)
+  if engine == :sql_server
+    unless %w[explain workload].include?(action)
+      abort "--engine sql_server is supported only by db explain and db workload"
+    end
+
+    workspace = Mxrb::Runtime::SqlServerDatabase.new(
+      server: option.call("--server"), database: option.call("--database"),
+      user: option.call("--user"), sqlcmd: option.call("--sqlcmd", "sqlcmd")
+    )
+  elsif engine == :postgresql
+    workspace = Mxrb::Runtime::DatabaseWorkspace.new(path, port:, runtime_port:)
+  else
+    abort "Unsupported database engine #{engine.inspect}; use postgresql or sql_server"
+  end
+  case action
+  when "up", "sync"
+    info = action == "sync" ? workspace.sync : workspace.up
+    puts "[mxrb] PostgreSQL and Mendix Runtime started"
+    puts "Host     : #{info.host}:#{info.port}"
+    puts "Database : #{info.database}"
+    puts "Role     : #{info.reader_user} (read-only)"
+    puts "Runtime  : #{info.runtime_url}"
+  when "down"
+    workspace.down
+    puts "[mxrb] Runtime and PostgreSQL stopped; the data volume was preserved"
+  when "destroy"
+    abort "db destroy requires --yes" unless ARGV.delete("--yes")
+    workspace.destroy(confirm: true)
+    puts "[mxrb] Removed the isolated containers, volume, network, and local state"
+  when "status"
+    info = workspace.status
+    puts "Running  : #{info.running}"
+    puts "Database : #{info.database_container}"
+    puts "Runtime  : #{info.runtime_container}"
+    puts "State    : #{info.state_dir}"
+  when "url"
+    puts workspace.connection_url
+  when "sql"
+    sql = ARGV.shift or abort "Usage: mxrb db sql <file.mpr> \"SELECT ...\" [--write]"
+    write = ARGV.delete("--write")
+    puts workspace.query(sql, write:)
+  when "explain"
+    sql = ARGV.shift or
+      abort "Usage: mxrb db explain <file.mpr> \"SELECT ...\" [--analyze] [--json]"
+    analyze = ARGV.delete("--analyze") == "--analyze"
+    json = ARGV.delete("--json") == "--json"
+    report = workspace.explain(sql, analyze:)
+    render_plan_report(report, json:)
+  when "workload"
+    limit = option.call("--limit", 20)
+    save = option.call('--save')
+    compare = option.call('--compare')
+    json = ARGV.delete("--json") == "--json"
+    report = workspace.workload(limit:)
+    File.write(save, Mxrb::Oql::WorkloadBaseline.dump(report)) if save
+    comparison = Mxrb::Oql::WorkloadBaseline.compare(report, compare) if compare
+    render_workload_report(report, json:)
+    unless json
+      comparison&.deltas&.each do |delta|
+        puts "[DELTA] #{delta.query_id} #{delta.metric}: #{delta.change_percent}%"
+      end
+    end
+  when "indexes"
+    abort 'db indexes currently requires PostgreSQL' unless engine == :postgresql
+
+    limit = option.call('--limit', 50)
+    json = ARGV.delete('--json') == '--json'
+    render_index_advice(workspace.index_advice(limit:), json:)
+  when "shell"
+    write = ARGV.delete("--write")
+    exec(*workspace.shell_command(write:))
+  else
+    abort "Unknown db action #{action.inspect}; " \
+          "use up, sync, down, destroy, status, url, sql, explain, workload, indexes or shell"
+  end
+
+when "serve"
+  path = ARGV.shift or abort "Usage: mxrb serve <file.mpr> [--port PORT] [--db-port PORT] [--no-up]"
+  option = lambda do |name, fallback|
+    index = ARGV.index(name)
+    next fallback unless index
+
+    abort "#{name} requires a value" unless ARGV[index + 1]
+    ARGV.slice!(index, 2).last
+  end
+  port = option.call("--port", 4567)
+  database_port = option.call("--db-port", 55_432)
+  prepare = !ARGV.delete("--no-up")
+  server = Mxrb::Oql::Server.new(path, port:, database_port:)
+  puts "[mxrb] Read-only query server: http://127.0.0.1:#{port}/query"
+  puts "[mxrb] Accepts POST JSON with an sql or oql field"
+  trap("INT") { Thread.new { server.shutdown } }
+  server.start(prepare:)
+
+when "search"
+  query = ARGV.shift or
+    abort "Usage: mxrb search <text> <file.mpr> [--backend auto|tfidf|onnx] [--limit N]"
+  path = ARGV.shift or
+    abort "Usage: mxrb search <text> <file.mpr> [--backend auto|tfidf|onnx] [--limit N]"
+  option = lambda do |name, fallback|
+    index = ARGV.index(name)
+    next fallback unless index
+
+    abort "#{name} requires a value" unless ARGV[index + 1]
+    ARGV.slice!(index, 2).last
+  end
+  backend = option.call("--backend", "auto").to_sym
+  limit = option.call("--limit", 10)
+  json = ARGV.delete("--json")
+  begin
+    hits = Mxrb.open(path) { _1.semantic_search_hits(query, backend:, limit:) }
+  rescue ArgumentError, LoadError => e
+    abort "[mxrb] error: #{e.message}"
+  end
+  if json
+    puts JSON.pretty_generate(
+      hits.each_with_index.map do |hit, index|
+        {
+          rank: index + 1, qualified_name: hit.artifact.qualified_name,
+          kind: hit.artifact.kind, distance: hit.distance
+        }
+      end
+    )
+  else
+    puts "rank\tdistance\tqualified_name\tkind"
+    hits.each_with_index do |hit, index|
+      puts [
+        index + 1, format("%.6f", hit.distance), hit.artifact.qualified_name, hit.artifact.kind
+      ].join("\t")
+    end
+  end
+
+when "find"
+  path = ARGV.shift or abort "Usage: mxrb find <file.mpr> <text> [--semantic]"
+  query = ARGV.shift or abort "Usage: mxrb find <file.mpr> <text> [--semantic]"
+  semantic = ARGV.delete("--semantic")
+  Mxrb.open(path) do |project|
+    results = if semantic
+                project.semantic_search_artifacts(query)
+              else
+                project.search_artifacts(query)
+              end
+    results.each do |artifact|
+      puts "#{artifact.qualified_name}\t#{artifact.kind}"
+    end
+  end
+
+when "evaluate"
+  path = ARGV.shift or abort "Usage: mxrb evaluate <file.mpr> <evaluation.rb>"
+  definition = ARGV.shift or abort "Usage: mxrb evaluate <file.mpr> <evaluation.rb>"
+  abort "#{definition}: file not found" unless File.file?(definition)
+  result = Mxrb.open(path) do |project|
+    Mxrb::Evaluation::Suite.new(project).evaluate(definition).run
+  end
+  result.checks.each do |check|
+    status = check.passed? ? "pass" : check.severity
+    puts "[#{status}] #{check.name}: #{check.message}"
+  end
+  puts "[mxrb] score #{format('%.2f', result.score)}% " \
+       "(#{result.checks.count(&:passed?)}/#{result.checks.size})"
+  exit 1 unless result.passed?
+
+when "test"
+  path = ARGV.shift or abort "Usage: mxrb test <file.mpr> <functional_test.rb> [--plan]"
+  definition_path = ARGV.shift or abort "Usage: mxrb test <file.mpr> <functional_test.rb> [--plan]"
+  abort "#{definition_path}: file not found" unless File.file?(definition_path)
+  plan_only = ARGV.delete("--plan")
+  docker = ARGV.delete("--docker")
+  native = ARGV.delete("--native")
+  abort "--native and --docker are mutually exclusive" if native && docker
+  report_option = lambda do |name|
+    index = ARGV.index(name)
+    next unless index
+
+    abort "#{name} requires a path" unless ARGV[index + 1]
+    ARGV.slice!(index, 2).last
+  end
+  json_report = report_option.call("--json")
+  junit_report = report_option.call("--junit")
+
+  definition = Mxrb.functional_definition(definition_path)
+  plan = Mxrb.runtime_plan(path)
+  if plan_only
+    puts "Mendix       : #{plan.mendix_version}"
+    puts "Java         : #{plan.java_version}"
+    puts "JDK builder  : #{plan.jdk_package}"
+    puts "JRE runtime  : #{plan.jre_package}"
+    puts "Toolchain    : #{plan.toolchain_path} (#{plan.available? ? 'available' : 'missing'})"
+    puts "Tests        : #{definition.tests.size}"
+    definition.tests.each { puts "  #{_1.name} -> #{_1.target}" }
+    puts "Build         : MXRB native host compiler (no mxbuild)"
+  else
+    executor = if native
+                 Mxrb::Runtime::Native::Executor
+               elsif docker
+                 Mxrb::Runtime::DockerExecutor
+               else
+                 Mxrb::Runtime::Executor
+               end
+    execution = executor.new(
+      path, definition, plan: plan, output: $stdout
+    ).run
+    execution.result.tests.each do |test|
+      puts "[#{test.passed? ? 'pass' : 'fail'}] #{test.name}: #{test.message}"
+    end
+    puts "[mxrb] #{execution.result.tests.count(&:passed?)}/" \
+         "#{execution.result.tests.size} passed in #{format('%.2f', execution.elapsed)}s"
+    reporter = Mxrb::Functional::Reporter.new
+    reporter.write_json(execution, json_report) if json_report
+    reporter.write_junit(execution, junit_report) if junit_report
+    exit 1 unless execution.passed?
+  end
+
+when "functional-instrument"
+  path = ARGV.shift or abort "Usage: mxrb functional-instrument <writable.mpr> <functional_test.rb>"
+  definition_path = ARGV.shift or
+    abort "Usage: mxrb functional-instrument <writable.mpr> <functional_test.rb>"
+  definition = Mxrb.functional_definition(definition_path)
+  instrumenter = Mxrb::Functional::Instrumenter.new(path, definition).instrument!
+  puts "[mxrb] Instrumented #{definition.tests.size} tests; runner #{instrumenter.runner}"
+
+when "team-server"
+  usage = <<~USAGE
+    Usage: mxrb team-server <login|projects|info|branches|commits|clone|status|fetch|pull|push> ...
+
+      team-server login --pat-file FILE
+          Store only FILE's absolute path; the PAT is never copied into MXRB.
+      team-server projects [--pat-file FILE]
+          List every company-owned project through the official Projects API.
+      team-server info APP_ID [--pat-file FILE]
+      team-server branches APP_ID [--pat-file FILE]
+      team-server commits APP_ID BRANCH [--pat-file FILE]
+          Query the official App Repository API.
+      team-server clone APP_ID|URL TARGET [--branch NAME] [--depth N] [--pat-file FILE]
+          Clone through Git HTTPS and validate every root MPR with MXRB.
+      team-server status|fetch|pull PATH [--pat-file FILE]
+      team-server push PATH [--remote NAME] [--branch NAME] [--pat-file FILE]
+
+    Authentication:
+      Recommended: --pat-file FILE or MXRB_TEAM_SERVER_PAT_FILE=/absolute/path/.env
+      FILE may be plain text, JSON, or .env with MXRB_TEAM_SERVER_PAT=...
+      Without a PAT file Git operations use the user's configured Git credential helper.
+      Required scopes: mx:modelrepository:repo:read (read) and
+      mx:modelrepository:repo:write (push).
+
+    PAT values are passed via a temporary GIT_ASKPASS helper. They are never
+    embedded in repository URLs, command arguments, or .git/config.
+  USAGE
+  action = ARGV.shift
+  if action.nil? || %w[-h --help help].include?(action)
+    puts usage
+    exit(action.nil? ? 1 : 0)
+  end
+  option = lambda do |name|
+    index = ARGV.index(name)
+    next unless index
+
+    abort "#{name} requires a value" unless ARGV[index + 1]
+    ARGV.slice!(index, 2).last
+  end
+  pat_file = option.call("--pat-file")
+  credentials = Mxrb::TeamServer::Credentials.new(pat_file:)
+  repository = Mxrb::TeamServer::Repository.new(credentials:)
+  api = -> { Mxrb::TeamServer::Api.new(credentials:) }
+  begin
+    case action
+    when "login"
+      abort "Usage: mxrb team-server login --pat-file FILE" unless pat_file && ARGV.empty?
+      path = credentials.configure_pat_file(pat_file)
+      puts "[mxrb] Stored Team Server PAT file reference in #{path}"
+      puts "[mxrb] The PAT remains in #{File.expand_path(pat_file)} and is read only for requests."
+    when "info"
+      app_id = ARGV.shift or abort "Usage: mxrb team-server info APP_ID [--pat-file FILE]"
+      abort "Unknown arguments: #{ARGV.join(' ')}" unless ARGV.empty?
+      puts JSON.pretty_generate(api.call.info(app_id))
+    when "projects"
+      abort "Unknown arguments: #{ARGV.join(' ')}" unless ARGV.empty?
+      puts JSON.pretty_generate(Mxrb::TeamServer::ProjectsApi.new(credentials:).all)
+    when "branches"
+      app_id = ARGV.shift or abort "Usage: mxrb team-server branches APP_ID [--pat-file FILE]"
+      abort "Unknown arguments: #{ARGV.join(' ')}" unless ARGV.empty?
+      puts JSON.pretty_generate(api.call.branches(app_id))
+    when "commits"
+      app_id = ARGV.shift or abort "Usage: mxrb team-server commits APP_ID BRANCH [--pat-file FILE]"
+      branch = ARGV.shift or abort "Usage: mxrb team-server commits APP_ID BRANCH [--pat-file FILE]"
+      abort "Unknown arguments: #{ARGV.join(' ')}" unless ARGV.empty?
+      puts JSON.pretty_generate(api.call.commits(app_id, branch))
+    when "clone"
+      source = ARGV.shift or abort "Usage: mxrb team-server clone APP_ID|URL TARGET [options]"
+      target = ARGV.shift or abort "Usage: mxrb team-server clone APP_ID|URL TARGET [options]"
+      branch = option.call("--branch")
+      depth = option.call("--depth")
+      abort "Unknown arguments: #{ARGV.join(' ')}" unless ARGV.empty?
+      result = repository.clone(source, target:, branch:, depth:)
+      puts "[mxrb] Cloned #{result.repository_url} to #{result.root}"
+      result.mpr_files.each { puts "[mxrb] Valid MPR: #{_1}" }
+    when "status", "fetch", "pull"
+      root = ARGV.shift || Dir.pwd
+      abort "Unknown arguments: #{ARGV.join(' ')}" unless ARGV.empty?
+      result = repository.public_send(action, root)
+      puts(result.respond_to?(:output) ? result.output : result)
+    when "push"
+      root = ARGV.shift || Dir.pwd
+      remote = option.call("--remote") || "origin"
+      branch = option.call("--branch")
+      abort "Unknown arguments: #{ARGV.join(' ')}" unless ARGV.empty?
+      result = repository.push(root, remote:, branch:)
+      puts result.output
+    else
+      abort "Unknown team-server action #{action.inspect}"
+    end
+  rescue Mxrb::TeamServerError => e
+    warn "[mxrb] Team Server: #{e.message}"
+    if e.message.match?(/Username|auth/i)
+      warn "[mxrb] Configure a PAT file with: mxrb team-server login --pat-file FILE"
+    end
+    exit 1
+  end
+
+when "marketplace"
+  marketplace_usage = <<~USAGE
+    Usage: mxrb marketplace <login|search|show|versions|pull|dependencies|update|remove|import|audit|list|verify> ...
+
+      marketplace login --pat-file FILE [--no-verify]
+          Recommended: store only a path and read the PAT from FILE or a Ruby .env.
+      marketplace login --store-pat [--no-verify]
+          Explicit opt-in: store the PAT in MXRB's own credentials file.
+      marketplace search NAME [--private|--public] [--approved] [--published-since DATE]
+          Search public and company-private content through the official Content API.
+      marketplace show <NAME|CONTENT_ID>
+          Show publisher, type, support, license, privacy, approval, and latest version.
+      marketplace versions <NAME|CONTENT_ID> [--mendix-version VERSION]
+          List releases, compatibility, notes, and vulnerability/security-fix metadata.
+      marketplace import FILE.mpk --mpr FILE.mpr
+          Import an official Mendix module package directly with Ruby/SQLite/BSON.
+      marketplace pull NAME[@VERSION] --mpr FILE.mpr [--mendix-version VERSION]
+          Download official Module, Service, or Widget content and install it transactionally.
+      marketplace pull github:ORG/REPO --mpr FILE.mpr
+          Use a public GitHub release instead of the official Marketplace.
+      marketplace update NAME[@VERSION] [--mpr FILE.mpr] [--apply]
+          Preview a reference-safe official update; mutate only with --apply.
+      marketplace remove NAME [--mpr FILE.mpr] [--apply]
+          Preview reference-safe removal; mutate only with --apply.
+      marketplace dependencies NAME [--mpr FILE.mpr] [--apply|--apply-resolved]
+          Resolve module references and WidgetIds; verify every downloaded MPK identity.
+      marketplace audit [--target DIR] [--mendix-version VERSION]
+          Check locked official components for updates and known vulnerabilities.
+      marketplace list|verify [--target DIR]
+          Inspect or verify .mxrb/marketplace.lock.json and cached packages.
+
+    Module/widget installation does not invoke mx, mxcli, Studio Pro, or the Model SDK.
+  USAGE
+  marketplace_login_usage = <<~USAGE
+    Usage:
+      mxrb marketplace login --pat-file FILE [--no-verify]  # recommended
+      mxrb marketplace login --store-pat [--no-verify]      # explicit opt-in
+
+    The recommended mode stores only FILE's absolute path in
+    $XDG_CONFIG_HOME/mxrb/credentials (default: ~/.config/mxrb/credentials).
+    MXRB does not copy, move, chmod, or rewrite FILE. It reads the PAT only when
+    an official Marketplace operation needs authentication.
+
+    FILE may be plain text, JSON with {"mendix_pat":"..."}, or a Ruby .env with:
+      MXRB_MENDIX_PAT=your_pat
+
+    --store-pat stores {"mendix_pat":"..."} directly in MXRB's credentials
+    file with mode 0600. The command shows the destination before prompting.
+
+    Environment-only alternative (nothing is persisted by login):
+      MXRB_MENDIX_PAT_FILE=/absolute/path/.env mxrb marketplace search NAME
+
+    A direct MXRB_MENDIX_PAT value remains supported and takes precedence, but
+    can be exposed through shell history/process environments. Required scope:
+    mx:marketplace-content:read.
+  USAGE
+  action = ARGV.shift
+  if action.nil? || %w[-h --help help].include?(action)
+    puts marketplace_usage
+    exit(action.nil? ? 1 : 0)
+  end
+  if action == 'login' && ARGV.any? { %w[-h --help help].include?(_1) }
+    puts marketplace_login_usage
+    exit 0
+  end
+  option = lambda do |name|
+    index = ARGV.index(name)
+    next unless index
+
+    abort "#{name} requires a value" unless ARGV[index + 1]
+    ARGV.slice!(index, 2).last
+  end
+  mpr = option.call('--mpr')
+  target = option.call('--target') || (mpr ? File.dirname(File.expand_path(mpr)) : Dir.pwd)
+  plan_state = lambda do |plan|
+    next 'partial applied' if plan.applied? && !plan.safe?
+    next 'applied' if plan.applied?
+
+    plan.safe? ? 'safe preview' : 'blocked preview'
+  end
+  print_lifecycle_plan = lambda do |plan|
+    state = plan_state.call(plan)
+    version = plan.target_version ? " -> #{plan.target_version}" : ''
+    puts "[mxrb] #{plan.action} #{plan.name} #{plan.installed_version}#{version}: #{state}"
+    plan.changes.each { puts "  change: #{_1}" }
+    plan.blockers.each { puts "  blocker: #{_1}" }
+  end
+  begin
+    case action
+    when 'login'
+      pat_file = option.call('--pat-file')
+      store_pat = ARGV.delete('--store-pat')
+      no_verify = ARGV.delete('--no-verify')
+      abort '--pat-file and --store-pat are mutually exclusive' if pat_file && store_pat
+      unless ARGV.empty?
+        abort "Unknown marketplace login option(s): #{ARGV.join(' ')}\n\n#{marketplace_login_usage}"
+      end
+      unless pat_file || store_pat
+        warn marketplace_login_usage
+        exit 1
+      end
+
+      credentials = Mxrb::OfficialMarketplace::Credentials.new
+      if pat_file
+        secret_path = File.expand_path(pat_file)
+        path = credentials.configure_pat_file(secret_path)
+        Mxrb::OfficialMarketplace::ContentApi.new(pat: credentials.pat).search(limit: 1) unless no_verify
+        puts "[mxrb] PAT file reference saved to #{path}"
+        puts "[mxrb] Secret remains in #{secret_path}; MXRB reads it only for Marketplace requests."
+      else
+        puts '[mxrb] Explicit managed-secret mode selected.'
+        puts "[mxrb] Destination: #{credentials.path}"
+        puts '[mxrb] Format: JSON field "mendix_pat"; file mode: 0600.'
+        puts '[mxrb] Recommended alternative: marketplace login --pat-file PATH'
+        print 'Mendix PAT: '
+        token = ENV['MXRB_MENDIX_PAT'] || $stdin.noecho(&:gets)
+        puts
+        Mxrb::OfficialMarketplace::ContentApi.new(pat: token).search(limit: 1) unless no_verify
+        path = credentials.save_pat(token)
+        puts "[mxrb] PAT stored by MXRB at #{path}"
+      end
+    when 'search'
+      query = ARGV.shift or abort 'Usage: mxrb marketplace search <query>'
+      source = option.call('--source') || 'official'
+      if source == 'github'
+        results = Mxrb::OfficialMarketplace::GitHubResolver.new.search(query)
+        results.each { puts "#{_1[:name]}\t#{_1[:repository]}\t#{_1[:description]}" }
+      else
+        abort "Unknown Marketplace source #{source.inspect}" unless source == 'official'
+
+        private_flag = ARGV.delete('--private')
+        public_flag = ARGV.delete('--public')
+        abort '--private and --public are mutually exclusive' if private_flag && public_flag
+        private_filter = true if private_flag
+        private_filter = false if public_flag
+        approved = true if ARGV.delete('--approved')
+        results = Mxrb::OfficialMarketplace::ContentApi.new.search(
+          name: query, private: private_filter, approved:,
+          published_since: option.call('--published-since'), limit: option.call('--limit') || 10
+        )
+        results.each do |item|
+          latest = item.fetch('latestVersion', {})
+          visibility = item['isPrivate'] ? 'private' : 'public' # rubocop:disable Metrics/BlockNesting
+          puts [item['contentId'], latest['name'], latest['versionNumber'], item['type'],
+                item['publisher'], visibility].join("\t")
+        end
+        puts "[mxrb] #{results.size} official Marketplace result(s)"
+      end
+    when 'show'
+      identifier = ARGV.shift or abort 'Usage: mxrb marketplace show <name|content_id>'
+      puts JSON.pretty_generate(Mxrb::OfficialMarketplace::ContentApi.new.find(identifier))
+    when 'versions'
+      identifier = ARGV.shift or abort 'Usage: mxrb marketplace versions <name|content_id>'
+      api = Mxrb::OfficialMarketplace::ContentApi.new
+      content = api.find(identifier)
+      mendix_version = option.call('--mendix-version')
+      published_since = option.call('--published-since')
+      versions = if mendix_version
+                   api.versions(content.fetch('contentId'), mendix_version:, published_since:)
+                 else
+                   api.all_versions(content.fetch('contentId'), published_since:)
+                 end
+      versions.each do |entry|
+        issues = Array(entry['vulnerabilities']) + Array(entry['fixedSecurityIssues'])
+        puts [entry['versionId'], entry['versionNumber'], entry['minSupportedMendixVersion'],
+              entry['versionType'], issues.filter_map { _1['code'] }.join(','),
+              entry['publicationDate']].join("\t")
+        puts "  #{entry['releaseNotes']}" unless entry['releaseNotes'].to_s.empty?
+      end
+      puts "[mxrb] #{versions.size} version(s)"
+    when 'pull'
+      identifier = ARGV.shift or
+        abort 'Usage: mxrb marketplace pull <name[@version]|github:org/repo> [--mpr FILE]'
+      source = option.call('--source') || (identifier.start_with?('github:') ? 'github' : 'official')
+      name, version = identifier.split('@', 2)
+      installer = Mxrb::OfficialMarketplace::Installer.new(target:, mpr:)
+      allow_vulnerable = !ARGV.delete('--allow-vulnerable').nil?
+      result = case source
+               when 'official'
+                 installer.pull_official(
+                   name, version:, mendix_version: option.call('--mendix-version'), allow_vulnerable:
+                 )
+               when 'github'
+                 installer.pull(name, version:)
+               else
+                 abort "Unknown Marketplace source #{source.inspect}"
+               end
+      puts "[mxrb] Installed #{result.package.name} #{result.package.version}"
+      puts "[mxrb] #{result.destination}"
+      puts "[mxrb] Imported #{result.units} MPR units without Studio Pro" if result.respond_to?(:units)
+      puts "[mxrb] SHA-256 #{result.sha256}"
+    when 'import'
+      path = ARGV.shift or
+        abort 'Usage: mxrb marketplace import <file.mpk> [--mpr FILE] [--target DIR]'
+      result = Mxrb::OfficialMarketplace::Installer.new(target:, mpr:).import(
+        path, name: option.call('--name')
+      )
+      puts "[mxrb] Imported #{result.package.name} into #{result.destination}"
+      puts "[mxrb] #{result.units} MPR units written without Studio Pro" if result.respond_to?(:units)
+      puts "[mxrb] SHA-256 #{result.sha256}"
+    when 'update'
+      identifier = ARGV.shift or
+        abort 'Usage: mxrb marketplace update <name[@version]> [--mpr FILE] [--apply]'
+      name, version = identifier.split('@', 2)
+      plan = Mxrb::OfficialMarketplace::Installer.new(target:, mpr:).update_official(
+        name, version:,
+              mendix_version: option.call('--mendix-version'),
+              allow_vulnerable: !ARGV.delete('--allow-vulnerable').nil?,
+              apply: !ARGV.delete('--apply').nil?
+      )
+      print_lifecycle_plan.call(plan)
+      exit 1 unless plan.safe?
+    when 'remove'
+      identifier = ARGV.shift or
+        abort 'Usage: mxrb marketplace remove <name> [--mpr FILE] [--apply]'
+      plan = Mxrb::OfficialMarketplace::Installer.new(target:, mpr:).remove(
+        identifier, apply: !ARGV.delete('--apply').nil?
+      )
+      print_lifecycle_plan.call(plan)
+      exit 1 unless plan.safe?
+    when 'dependencies'
+      identifier = ARGV.shift or
+        abort 'Usage: mxrb marketplace dependencies <name> [--mpr FILE] [--apply|--apply-resolved]'
+      apply = !ARGV.delete('--apply').nil?
+      apply_resolved = !ARGV.delete('--apply-resolved').nil?
+      abort '--apply and --apply-resolved are mutually exclusive' if apply && apply_resolved
+      plan = Mxrb::OfficialMarketplace::Installer.new(target:, mpr:).dependencies(
+        identifier, apply:, apply_resolved:
+      )
+      state = plan_state.call(plan)
+      puts "[mxrb] dependencies #{plan.root}: #{state}"
+      plan.changes.each { puts "  change: #{_1}" }
+      plan.blockers.each { puts "  blocker: #{_1}" }
+      exit 1 unless plan.safe?
+    when 'list'
+      packages = Mxrb::OfficialMarketplace.lock(target).fetch('packages')
+      packages.each { |name, entry| puts "#{name}\t#{entry['version']}\t#{entry['source']}" }
+      puts "[mxrb] #{packages.size} package(s)"
+    when 'audit'
+      results = Mxrb::OfficialMarketplace::SecurityAuditor.new(target:).audit(
+        mendix_version: option.call('--mendix-version')
+      )
+      results.each do |result|
+        state = result.version_type == 'Unknown' ? 'unknown' : 'vulnerable'
+        state = result.outdated ? 'update' : 'ok' if result.valid
+        puts [state, result.name, result.installed_version, result.latest_version,
+              result.version_type, result.issues.join(',')].join("\t")
+      end
+      puts "[mxrb] #{results.size} official Marketplace package(s) audited"
+      exit 1 unless results.all?(&:valid)
+    when 'verify'
+      results = Mxrb::OfficialMarketplace.verify(target)
+      results.each { |name, result| puts "#{result[:valid] ? 'ok' : 'changed'}\t#{name}" }
+      exit 1 unless results.values.all? { _1[:valid] }
+    else
+      abort "Unknown marketplace action #{action.inspect}"
+    end
+  rescue Mxrb::MarketplaceError => e
+    abort "[mxrb] error: #{e.message}"
+  end
+
+when "module"
+  action = ARGV.shift or abort "Usage: mxrb module <new|search|add> ..."
+  option = lambda do |name|
+    index = ARGV.index(name)
+    next unless index
+
+    abort "#{name} requires a value" unless ARGV[index + 1]
+    ARGV.slice!(index, 2).last
+  end
+  case action
+  when "new"
+    name = ARGV.shift or abort "Usage: mxrb module new <name> [--target DIR]"
+    target = option.call("--target") || Dir.pwd
+    begin
+      result = Mxrb::ModuleInitializer.new(name).scaffold(into: target)
+    rescue ArgumentError => e
+      abort "[mxrb] error: #{e.message}"
+    end
+    result.files.each { puts "  create  #{_1}" }
+    puts "  update  #{result.project_file}"
+    puts "\nDone. Run:"
+    puts "  bundle exec mxrb generate project.rb"
+  when "search"
+    registry = option.call("--registry")
+    catalog = Mxrb::Marketplace::Catalog.new(registry)
+    query = ARGV.shift
+    entries = catalog.search(query)
+    entries.each do |entry|
+      puts "#{entry.name}\t#{entry.version}\t#{entry.description}"
+    end
+    puts "[mxrb] #{entries.size} module(s)"
+  when "add"
+    registry = option.call("--registry")
+    catalog = Mxrb::Marketplace::Catalog.new(registry)
+    identifier = ARGV.shift or
+      abort "Usage: mxrb module add <name|directory> [--target DIR] [--registry SOURCE]"
+    target = option.call("--target") || Dir.pwd
+    installation = Mxrb::Marketplace::Installer.new(
+      target: target, catalog: catalog
+    ).install(identifier)
+    puts "[mxrb] Installed #{installation.entry.name} " \
+         "#{installation.entry.version} as #{installation.module_name}"
+    puts "[mxrb] #{installation.destination}"
+    puts "[mxrb] SHA-256 #{installation.digest}"
+  else
+    abort "Unknown module action #{action.inspect}; use new, search, or add"
+  end
+
+when 'scaffold'
+  action = ARGV.shift or abort 'Usage: mxrb scaffold <list|destroy> ...'
+  target_index = ARGV.index('--target')
+  target = if target_index
+             abort '--target requires a value' unless ARGV[target_index + 1]
+             ARGV.slice!(target_index, 2).last
+           else
+             Dir.pwd
+           end
+  case action
+  when 'list'
+    puts "command\tdestination"
+    Mxrb::Scaffold::Help::COMMANDS.each do |name, (_usage, _description, destination)|
+      puts "#{name}\t#{destination}"
+    end
+    registry = Mxrb::Scaffold::Registry.new(target).entries
+    unless registry.empty?
+      puts "\nregistered scaffold\tfiles"
+      registry.each { |key, entry| puts "#{key}\t#{entry.fetch('files').size}" }
+    end
+  when 'destroy'
+    key = ARGV.shift or abort 'Usage: mxrb scaffold destroy <kind:name> [--target DIR]'
+    removal = Mxrb::Scaffold::Registry.new(target).remove(key)
+    removal.files.each { puts "  remove  #{_1}" }
+  else
+    abort "Unknown scaffold action #{action.inspect}; use list or destroy"
+  end
+
+when *SCAFFOLD_COMMANDS
+  Mxrb::Scaffold::CLI.new(command, ARGV).run
+
+when "describe"
+  path = ARGV.shift or abort "Usage: mxrb describe <file.mpr> <qualified-name>"
+  name = ARGV.shift or abort "Usage: mxrb describe <file.mpr> <qualified-name>"
+  begin
+    Mxrb.open(path) do |project|
+      details = project.describe_artifact(name)
+      puts "#{details.artifact.qualified_name}\t#{details.artifact.kind}"
+      puts "Incoming:"
+      details.incoming.each do |reference|
+        puts "  #{reference.source.qualified_name}\t#{reference.relation}"
+      end
+      puts "Outgoing:"
+      details.outgoing.each do |reference|
+        puts "  #{reference.target.qualified_name}\t#{reference.relation}"
+      end
+    end
+  rescue KeyError, ArgumentError => e
+    warn "[mxrb] error: #{e.message}"
+    exit 1
+  end
+
+when "tree"
+  path = ARGV.shift or abort "Usage: mxrb tree <file.mpr> [module]"
+  selected_module = ARGV.shift
+  Mxrb.open(path) do |project|
+    artifacts = project.semantic_index.artifacts
+    artifacts = artifacts.select { _1.module_name == selected_module } if selected_module
+    artifacts.group_by(&:module_name).sort_by { |module_name, _| module_name.to_s }
+             .each do |module_name, module_artifacts|
+      puts module_name || "(project)"
+      module_artifacts.reject { _1.kind == :module }.group_by(&:kind)
+                      .sort_by { |kind, _| kind.to_s }.each do |kind, items|
+        puts "  #{kind}"
+        items.sort_by(&:qualified_name).each { puts "    #{_1.qualified_name}" }
+      end
+    end
+  end
+
+when "init"
+  name = ARGV.shift or abort "Usage: mxrb init <project_name> [--mxrb-path DIR]"
+  path_index = ARGV.index('--mxrb-path')
+  mxrb_path = path_index ? ARGV.slice!(path_index, 2).last : nil
+  abort '--mxrb-path requires a value' if path_index && mxrb_path.nil?
+  abort "Unknown arguments: #{ARGV.join(' ')}" unless ARGV.empty?
+  begin
+    result = Mxrb::Initializer.new(name, mxrb_path:).scaffold
+  rescue ArgumentError => e
+    abort "[mxrb] error: #{e.message}"
+  end
+  result.files.each { puts "  create  #{_1}" }
+  puts "\nDone. Next steps:"
+  puts "  cd #{result.root}"
+  puts "  bundle install"
+  puts "  bundle exec mxrb generate project.rb"
+
+else
+  puts <<~USAGE
+    mxrb — Pure-Ruby Mendix .mpr toolkit
+
+    Commands:
+      doctor     [DIR] [--json]           Check project files and local toolchain
+      benchmark <file.mpr>                Measure open, index and validation time
+                 --iterations N --json    Configure repetitions or emit JSON
+      project inspect [DIR] [--json]      Inventory version, modules, MPRs and scaffolds
+      upgrade --mendix VERSION            Preview a project.rb version upgrade
+                 [--target DIR] --apply   Apply the version change transactionally
+      migrate check|plan [DIR] [--json]   Compare project.rb output with the current MPR
+      inspect    <file.mpr>               Full unit dump (exploration)
+      dump-unit  <file.mpr> <unit_id>     Hex dump of a unit's Contents blob
+      sql        <file.mpr> "SELECT …"    Run raw SQL against the .mpr SQLite
+      modules    <file.mpr>               List all modules
+      init       <project_name>           Scaffold a new Ruby-first Mendix project
+                 --mxrb-path DIR          Use a local MXRB checkout in the Gemfile
+      generate   <definition.rb> [mpr]    Apply a Ruby DSL definition
+      pack       <file.mpr>                Build an MDA from a materialized deployment
+                 --output FILE [--force]   Pure Ruby container writer; never calls mx/mxbuild
+      portable   <file.mpr>                Build an executable portable Runtime ZIP
+                 --output FILE             Uses installed Runtime files; never calls mx/mxbuild
+      mda inspect|compare <file.mda>       Inspect or diff MDA contents and metadata
+      widgets sync <definition.rb> <mpr>  Synchronize pluggable widget schemas
+      frontend migrate <file.mpr>         Preview frontend schema/layout/theme migration
+                 [--apply] [--json]       Apply only a safe plan or emit structured output
+      export     <file.mpr> <directory>   Convert an MPR to editable Ruby
+      validate   <file.mpr>               Check MPR structure, hashes and v2 contents
+      preflight  <file.mpr> [--json]      Audit native compiler/runtime compatibility
+      compare    <left.mpr> <right.mpr>   Compare structural MPR snapshots
+      diff       <left.mpr> <right.mpr>   Print typed semantic changes
+      refs       <file.mpr> <name>        Find references to a Mendix artifact
+      callers    <file.mpr> <name>        List callers of a callable artifact
+      callees    <file.mpr> <name>        List artifacts called by a callable artifact
+      impact     <file.mpr> <name>        Find transitive dependents
+      rename     <mpr> <old> <new>         Preview a safe model-wide rename
+                 --apply                   Apply the previewed rename
+      remove     <mpr> <name>              Preview a reference-safe unit removal
+                 --apply                   Apply only when no refs/children exist
+      move       <mpr> <name> <container>  Preview a same-module unit move
+                 --apply                   Move into a module or folder
+      lint       <file.mpr>                Ruby semantic diagnostics
+      report     <file.mpr>                Coupling and reference summary
+      cache status <file.mpr> [--json]     Inspect semantic cache health and size
+            warm <file.mpr> [--json]       Build or refresh the semantic cache
+           clear <file.mpr> [--json]       Remove semantic cache entries
+      oql        <file.mpr> [--json]        Show native OQL and a read-only SQL view
+                 --dialect DIALECT          ansi, postgresql (default), or sql_server
+      analyze    <file.mpr> [--json]        Analyze every native OQL query
+                 --sql "SELECT ..."         Analyze ad-hoc SQL instead of an MPR
+                 --oql "SELECT ..."         Analyze ad-hoc OQL instead of an MPR
+                 --dialect DIALECT          Dialect-specific actionable suggestions
+      design scan <file.mpr> [--json]       Inventory CSS and SCSS design tokens
+             migrate <mpr> <literal> <token> Preview a literal-to-token migration
+                 --apply                    Apply the asset migration atomically
+      db up      <file.mpr> [--port PORT] [--runtime-port PORT]
+                                            Build, synchronize and expose PostgreSQL and Runtime
+         sync    <file.mpr> [--port PORT] [--runtime-port PORT]
+                                            Rebuild and synchronize the retained database
+         down    <file.mpr>                 Stop containers while preserving all data
+         destroy <file.mpr> --yes           Remove isolated containers, data, and state
+         status  <file.mpr>                 Show isolated database/runtime status
+         url     <file.mpr> [--port PORT]   Print the read-only PostgreSQL connection URL
+         sql     <file.mpr> "SELECT …"      Execute SQL as the read-only analyst role
+                 --write                    Explicitly use the Runtime owner role
+         explain <file.mpr> "SELECT …"      Inspect PostgreSQL plan and index findings
+                 --analyze                  Execute the read-only query with buffers/timing
+                 --json                     Emit a machine-readable plan report
+                 --engine sql_server        Use an explicit SQL Server deployment
+                 --server HOST --database DB --user USER
+                                            Read password from MXRB_SQLSERVER_PASSWORD
+                 --sqlcmd PATH              Override the sqlcmd executable
+         workload <file.mpr> [--limit N]    Rank pg_stat_statements and schema pressure
+                 --json                     Emit queries, table/index stats, and findings
+                 --save FILE                Save a workload performance baseline
+                 --compare FILE             Report regressions against a saved baseline
+         indexes <file.mpr> [--limit N]     Advise evidence-backed PostgreSQL indexes
+                 --json                     Emit candidates and overlaps as JSON
+         shell   <file.mpr> [--write]       Open psql (read-only by default)
+      serve      <file.mpr> [--port 4567]   Serve read-only SQL/OQL over loopback HTTP
+                 --db-port PORT             Runtime PostgreSQL host port (default 55432)
+                 --no-up                    Reuse an already-running database workspace
+      search     <text> <file.mpr>          Semantic search with ranked distances
+                 --backend NAME             auto, tfidf, or onnx
+                 --limit N                  Maximum results (default 10)
+      find       <file.mpr> <text>         Search artifacts by name
+      describe   <file.mpr> <name>         Show incoming and outgoing references
+      tree       <file.mpr> [module]       Browse the semantic structure
+      evaluate   <file.mpr> <eval.rb>      Run Ruby model evaluations
+      module search [query]                Search the Ruby module marketplace
+             add <name|directory>          Install a module and write its lockfile
+             new <name> [--target DIR]     Scaffold and connect an application module
+      marketplace login --pat-file FILE   Reference a PAT file (--help for secure modes)
+                  search <name>            Search the official Content API
+                  show <name|content-id>   Show official component metadata
+                  versions <name|id>       List compatibility and security metadata
+                  pull <name|id|github:o/r> Download/import a release [--mpr FILE]
+                  import <file.mpk>        Import a module directly [--mpr FILE]
+                  audit                    Check locked updates and vulnerabilities
+                  list|verify              Inspect or verify locked official packages
+      team-server clone APP_ID|URL TARGET Clone and validate a Mendix Team Server app
+                  info|branches|commits    Query the official App Repository API
+                  status|fetch|pull|push    Synchronize through Git without mx
+      scaffold list [--target DIR]         List generators and registered scaffolds
+               destroy <kind:name>         Remove an unchanged registered scaffold
+      entity new Module.Name              Scaffold a domain entity (--help for details)
+      enumeration new Module.Name         Scaffold an enumeration
+      use-case new Module.Name            Scaffold an application use case
+      validation new Module.Name          Scaffold a validation flow
+      query new Module.Name               Scaffold a query flow
+      functional-test new Module.Flow     Scaffold a runtime functional test
+      evaluation new Name                 Scaffold static model evaluations
+      presentation init Module            Initialize presentation directories
+      page templates [--json]             List audited page patterns as a tree
+      page new|generate|g Module.Name      Scaffold a page
+                 [--template NAME]         Apply starter/blank/dashboard/form-vertical
+                 [--chain CHAIN]           Compose page/nanoflow/microflow actions
+      nanoflow new Module.Name            Scaffold a client nanoflow
+      repository new Module.Name          Scaffold a repository port and adapter
+      security init Module                Scaffold module roles
+      scheduled-event new Module.Name     Scaffold an event and handler
+      constant new Module.Name            Scaffold a module constant
+      integration new Module.Name         Scaffold an integration adapter
+      published-rest new Module.Name      Scaffold a published REST handler
+      consumed-rest new Module.Name       Scaffold a consumed REST adapter
+      java-action new Module.Name         Scaffold a Java Action adapter
+      design init                         Initialize design-system Ruby
+      ci init github                      Scaffold GitHub Actions
+      test       <file.mpr> <test.rb>      Run isolated functional runtime tests
+                 --native                  Use the Ruby model Runtime; no Java/mxbuild
+                 --docker                  Run the natively built package in a disposable Runtime container
+                 --plan                    Show toolchain and Docker execution plan
+                 --json PATH               Write a machine-readable result
+                 --junit PATH              Write a JUnit-compatible result
+  USAGE
+end