mxrb 0.1.0

data/lib/mxrb/runtime/toolchain.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Mxrb
+  module Runtime
+    RUNTIME_REQUIRED_FILES = %w[launcher/runtimelauncher.jar].freeze
+
+    Plan = Data.define(
+      :mendix_version, :java_version, :toolchain_path,
+      :mx_path, :mxbuild_path, :jdk_package, :jre_package,
+      :builder_image, :runtime_image
+    ) do
+      def runtime_path = File.join(toolchain_path, 'runtime')
+
+      def available?
+        RUNTIME_REQUIRED_FILES.all? { File.file?(File.join(runtime_path, _1)) }
+      end
+    end
+
+    class Toolchain
+      def initialize(project_path, mendix_home: nil)
+        @project_path = File.expand_path(project_path)
+        @mendix_home = mendix_home && File.expand_path(mendix_home)
+      end
+
+      def plan
+        version, java = project_metadata
+        root = toolchain_root(version)
+        Plan.new(
+          version, java, root,
+          File.join(root, "modeler", "mx"),
+          File.join(root, "modeler", "mxbuild"),
+          "zulu#{java}-ca-jdk-headless",
+          "zulu#{java}-ca-jre-headless",
+          "mxrb/mendix-builder:java#{java}",
+          "eclipse-temurin:#{java}-jre"
+        )
+      end
+
+      private
+
+      def project_metadata
+        Mxrb.open(@project_path) do |project|
+          [project.mendix_version, configured_java(project) || fallback_java(project.mendix_version)]
+        end
+      end
+
+      def configured_java(project)
+        project.all_units.each do |raw|
+          doc = project.parse_bson(raw)
+          next unless doc["$Type"] == "Settings$ProjectSettings"
+
+          settings = IO::BsonCodec.parse_array(doc["Settings"])[:items]
+          model = settings.find { _1["$Type"] == "Settings$ModelSettings" }
+          value = model && model["JavaMajorVersion"].to_s
+          return value if value&.match?(/\A\d+\z/)
+        end
+        nil
+      end
+
+      def fallback_java(version)
+        major, minor, patch = version.to_s.split(".").map(&:to_i)
+        return "7" if major <= 5
+        return "8" if major <= 7
+        return "11" if major == 8
+        return "11" if major == 9 && ([minor, patch] <=> [18, 16]).negative?
+        return "17" if major == 9
+        return "21" if major >= 11 || (major == 10 && minor >= 21)
+        return "17" if major == 10 && (minor > 6 || (minor == 6 && patch >= 7))
+
+        "11"
+      end
+
+      def toolchain_root(version)
+        candidates = [
+          @mendix_home && File.join(@mendix_home, version),
+          File.join(Dir.home, ".local", "share", "mendix", version)
+        ].compact
+        candidates.find { File.directory?(_1) } || candidates.first
+      end
+    end
+  end
+end

data/lib/mxrb/scaffold/cli.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Mxrb
+  module Scaffold
+    # Parses and renders the conventional scaffold subcommands.
+    class CLI
+      INIT_COMMANDS = %w[presentation security design ci].freeze
+      QUIET_COMMANDS = %w[ci evaluation functional-test].freeze
+
+      def initialize(command, argv, output: $stdout)
+        @command = command
+        @argv = argv
+        @output = output
+      end
+
+      def run
+        return show_help if help?
+        return render_page_templates if page_templates?
+
+        validate_action!
+        @dry_run = @argv.delete('--dry-run') ? true : false
+        @json = @argv.delete('--json') ? true : false
+        result = generator.scaffold
+        render(result)
+      rescue ArgumentError => e
+        abort "[mxrb] error: #{e.message}"
+      end
+
+      private
+
+      def generator
+        chain = extract_option('--chain') if @command == 'page'
+        template = extract_option('--template') if @command == 'page'
+        Generator.new(
+          kind, scaffold_name, target: target, dry_run: @dry_run,
+                               page_chain: chain, page_template: template
+        )
+      end
+
+      def page_templates? = @command == 'page' && @argv.first == 'templates'
+
+      def render_page_templates
+        @argv.shift
+        json = @argv.delete('--json')
+        abort "Unknown arguments: #{@argv.join(' ')}" unless @argv.empty?
+
+        @output.puts(json ? JSON.pretty_generate(PageTemplates.payload) : PageTemplates.tree)
+      end
+
+      def help?
+        @argv.first == '--help' || @argv.delete('--help')
+      end
+
+      def show_help
+        @output.puts Help.text(@command)
+      end
+
+      def validate_action!
+        action = @argv.shift
+        abort Help.text(@command) unless accepted_actions.include?(action)
+      end
+
+      def accepted_actions
+        return %w[new generate g] if @command == 'page'
+
+        [expected_action]
+      end
+
+      def expected_action
+        INIT_COMMANDS.include?(@command) ? 'init' : 'new'
+      end
+
+      def scaffold_name
+        return nil if @command == 'design'
+
+        @scaffold_name ||= @argv.shift || abort(Help.text(@command))
+      end
+
+      def target
+        value = extract_option('--target') || Dir.pwd
+        abort "Unknown arguments: #{@argv.join(' ')}" unless @argv.empty?
+        value
+      end
+
+      def extract_option(name)
+        index = @argv.index(name)
+        return unless index
+
+        abort "#{name} requires a value" unless @argv[index + 1]
+        @argv.slice!(index, 2).last
+      end
+
+      def kind = @command.tr('-', '_').to_sym
+
+      def render(result) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        if @json
+          return @output.puts JSON.pretty_generate(
+            kind: result.kind, name: result.name, dry_run: result.dry_run,
+            files: result.files, updated: result.updated
+          )
+        end
+
+        prefix = result.dry_run ? 'would create' : 'create'
+        result.files.each { @output.puts "  #{prefix}  #{_1}" }
+        result.updated.each { @output.puts "  update  #{_1}" }
+        return if QUIET_COMMANDS.include?(@command)
+
+        @output.puts "\nDone. Run:"
+        @output.puts '  bundle exec mxrb generate project.rb'
+      end
+    end
+  end
+end

data/lib/mxrb/scaffold/generator.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module Mxrb
+  module Scaffold
+    # Creates conventional Ruby-first artifacts and connects missing aggregators.
+    # rubocop:disable Metrics/ClassLength
+    class Generator
+      include Recipes
+
+      Result = Data.define(:root, :files, :updated, :kind, :name, :dry_run)
+      IDENTIFIER = /\A[A-Za-z][A-Za-z0-9_]*\z/
+      RESERVED_ENTITY_NAMES = %w[Owner ChangedBy CreatedDate ChangedDate].freeze
+      PAGE_CHAINS = %w[page:microflow page:nanoflow page:nanoflow:microflow].freeze
+      LAYER_AGGREGATORS = {
+        'domain' => 'model.rb',
+        'application' => 'application.rb',
+        'presentation' => 'presentation.rb',
+        'infrastructure' => 'infrastructure.rb'
+      }.freeze
+
+      def initialize(kind, name = nil, target: Dir.pwd, dry_run: false, **page_options)
+        @kind = kind.to_sym
+        @name = name.to_s
+        @root = File.expand_path(target)
+        @transaction = Transaction.new
+        @dry_run = dry_run
+        @page_chain = page_options.delete(:page_chain)
+        @page_template = page_options.delete(:page_template)
+        raise ArgumentError, "unknown generator options: #{page_options.keys.join(', ')}" unless
+          page_options.empty?
+      end
+
+      def scaffold
+        send("scaffold_#{@kind}")
+        registry = stage_registry unless @dry_run
+        @transaction.commit unless @dry_run
+        Result.new(
+          @root, visible(@transaction.created, registry), visible(@transaction.updated, registry),
+          @kind, @name, @dry_run
+        )
+      end
+
+      private
+
+      def page_chain
+        return unless @page_chain
+        return @page_chain if PAGE_CHAINS.include?(@page_chain)
+
+        raise ArgumentError,
+              "page chain must be one of: #{PAGE_CHAINS.join(', ')}"
+      end
+
+      def selected_page_template
+        PageTemplates.fetch(@page_template)&.name
+      end
+
+      def stage_registry
+        Registry.stage(
+          @transaction, root: @root, key: "#{@kind}:#{@name}", files: @transaction.created.dup
+        )
+      end
+
+      def visible(paths, registry)
+        paths.reject { _1 == registry }.freeze
+      end
+
+      def ensure_presentation(module_name)
+        ensure_module(module_name)
+        path = module_path(module_name, 'presentation', 'presentation.rb')
+        ensure_file(path, Templates.render(:presentation, module_name:, name: nil))
+        %w[pages snippets client_actions].each do |directory|
+          ensure_file(module_path(module_name, 'presentation', directory, '.keep'), '')
+        end
+        connect_module_aggregator(module_name, 'presentation', 'presentation.rb')
+      end
+
+      def ensure_infrastructure(module_name)
+        ensure_module(module_name)
+        path = module_path(module_name, 'infrastructure', 'infrastructure.rb')
+        ensure_file(path, Templates.render(:infrastructure, module_name:, name: nil))
+        connect_module_aggregator(module_name, 'infrastructure', 'infrastructure.rb')
+      end
+
+      def connect_artifact(aggregator, *segments)
+        source = @transaction.content(aggregator)
+        raise ArgumentError, "#{aggregator}: aggregator not found" unless source
+
+        line = artifact_evaluation(source, segments)
+        return if source.include?(line)
+
+        @transaction.write(aggregator, "#{source.rstrip}\n#{line}\n")
+      end
+
+      def artifact_evaluation(source, segments)
+        return evaluate_line(segments) unless source.match?(/^\s*evaluate_dir File\.join\(__dir__, /)
+
+        %(evaluate_dir File.join(__dir__, "#{segments.fetch(0)}"))
+      end
+
+      def connect_module_aggregator(module_name, *segments)
+        path = module_path(module_name, 'module.rb')
+        source = @transaction.content(path)
+        line = evaluate_line(segments)
+        @transaction.write(path, insert_before_closing(source, line, path)) unless source.include?(line)
+      end
+
+      def connect_project_file(*segments)
+        path = project_path('project.rb')
+        source = @transaction.content(path)
+        line = evaluate_line(segments)
+        @transaction.write(path, insert_before_closing(source, line, path)) unless source.include?(line)
+      end
+
+      def connect_project_security(module_name)
+        path = project_path('project.rb')
+        source = @transaction.content(path)
+        return if source.match?(/^\s*security do\s*$/)
+
+        lines = source.lines
+        version = lines.index { _1.match?(/^\s*mendix_version\s+/) }
+        raise ArgumentError, "#{path}: mendix_version not found" unless version
+
+        block = Templates.render(:project_security, module_name:, name: nil)
+        lines.insert(version + 1, "\n#{block.lines.map { "  #{_1}" }.join}")
+        @transaction.write(path, lines.join)
+      end
+
+      def insert_before_closing(source, line, path)
+        lines = source.lines
+        closing = lines.rindex { _1.strip == 'end' }
+        raise ArgumentError, "#{path}: closing end not found" unless closing
+
+        indentation = lines.filter_map { _1[/\A\s+(?=evaluate )/] }.first || '  '
+        lines.insert(closing, "#{indentation}#{line}\n")
+        lines.join
+      end
+
+      def create_module_file(module_name, directories, artifact_name, template, suffix: nil)
+        ensure_module(module_name)
+        filename = "#{Templates.snake_case(artifact_name)}#{suffix}.rb"
+        path = module_path(module_name, *directories, filename)
+        @transaction.create(path, Templates.render(template, module_name:, name: artifact_name))
+        filename
+      end
+
+      def create_connected_module_file(module_name, directories, artifact_name, template, suffix: nil)
+        filename = create_module_file(
+          module_name, directories, artifact_name, template, suffix:
+        )
+        layer, *relative = directories
+        aggregator = module_path(module_name, layer, LAYER_AGGREGATORS.fetch(layer))
+        connect_artifact(aggregator, *relative, filename)
+        filename
+      end
+
+      def create_connected_module_content(module_name, directories, artifact_name, content)
+        ensure_module(module_name)
+        filename = "#{Templates.snake_case(artifact_name)}.rb"
+        path = module_path(module_name, *directories, filename)
+        @transaction.create(path, content)
+        layer, *relative = directories
+        aggregator = module_path(module_name, layer, LAYER_AGGREGATORS.fetch(layer))
+        connect_artifact(aggregator, *relative, filename)
+        filename
+      end
+
+      def create_page_template(module_name, artifact_name, template:, chain:)
+        content = Templates.render(
+          :page_from_template, module_name:, name: artifact_name,
+                               template:, refresh_action: page_refresh_action(module_name, artifact_name, chain)
+        )
+        create_connected_module_content(
+          module_name, %w[presentation pages], artifact_name, content
+        )
+      end
+
+      def page_refresh_action(module_name, artifact_name, chain)
+        return unless chain
+        return "microflow: \"#{module_name}.ACT_Refresh#{artifact_name}\"" if
+          chain == 'page:microflow'
+
+        "nanoflow: \"#{module_name}.NAN_Refresh#{artifact_name}\""
+      end
+
+      def create_page_navigation(module_name, artifact_name)
+        project = @transaction.content(project_path('project.rb')).to_s
+        unless project.include?('evaluate_dir File.join(__dir__, "app", "navigation", "responsive")')
+          raise ArgumentError,
+                'page chain requires the generated Responsive navigation aggregator'
+        end
+
+        filename = "#{Templates.snake_case(module_name)}_#{Templates.snake_case(artifact_name)}.rb"
+        @transaction.create(
+          project_path('app', 'navigation', 'responsive', filename),
+          Templates.render(:page_chain_navigation, module_name:, name: artifact_name)
+        )
+      end
+
+      def create_project_file(directories, artifact_name, content)
+        path = project_path(*directories, "#{Templates.snake_case(artifact_name)}.rb")
+        @transaction.create(path, content)
+      end
+
+      def qualified_name
+        parts = @name.split('.', 2)
+        raise ArgumentError, 'name must be qualified as Module.Artifact' unless parts.size == 2
+
+        module_name = identifier(parts.first, label: 'module')
+        artifact_name = identifier(parts.last, label: 'artifact')
+        if @kind == :entity && RESERVED_ENTITY_NAMES.include?(artifact_name)
+          raise ArgumentError, "entity name #{artifact_name.inspect} is reserved by Mendix"
+        end
+
+        [module_name, artifact_name]
+      end
+
+      def module_only = identifier(@name, label: 'module')
+
+      def identifier(value, label:)
+        raise ArgumentError, "#{label} name must be a Mendix identifier" unless IDENTIFIER.match?(value)
+
+        value
+      end
+
+      def ensure_project
+        path = project_path('project.rb')
+        raise ArgumentError, "#{path}: project.rb not found" unless File.file?(path)
+      end
+
+      def ensure_module(module_name)
+        ensure_project
+        path = module_path(module_name, 'module.rb')
+        raise ArgumentError, "#{path}: module not found" unless File.file?(path)
+      end
+
+      def project_path(*segments) = File.join(@root, *segments)
+      def module_path(module_name, *segments) = project_path('modules', module_name, *segments)
+
+      def evaluate_line(segments)
+        quoted = segments.map { |segment| %("#{segment}") }.join(', ')
+        "evaluate File.join(__dir__, #{quoted})"
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/mxrb/scaffold/help.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Mxrb
+  module Scaffold
+    # Human-readable command catalog used by both top-level and subcommand help.
+    module Help
+      module_function
+
+      COMMANDS = {
+        'entity' => ['new Module.Entity', 'Create a domain entity file', 'domain/entities'],
+        'enumeration' => ['new Module.Enum', 'Create an enumeration', 'domain/enumerations'],
+        'use-case' => ['new Module.Flow', 'Create an application use case', 'application/use_cases'],
+        'validation' => ['new Module.Flow', 'Create a validation flow', 'application/validations'],
+        'query' => ['new Module.Flow', 'Create a query flow', 'application/queries'],
+        'functional-test' => ['new Module.Flow', 'Create a runtime test', 'functional_tests'],
+        'evaluation' => ['new Name', 'Create static model checks', 'evaluations'],
+        'presentation' => ['init Module', 'Initialize presentation directories', 'presentation'],
+        'page' => [
+          'new|generate|g Module.Page [--template NAME] [--chain CHAIN] | templates [--json]',
+          'Create a page or an executable page-led vertical slice',
+          'presentation or domain/application/presentation/navigation'
+        ],
+        'nanoflow' => ['new Module.Flow', 'Create a client nanoflow', 'presentation/client_actions'],
+        'repository' => ['new Module.Repository', 'Create repository port and adapter', 'application/infrastructure'],
+        'security' => ['init Module', 'Create module roles template', 'security'],
+        'scheduled-event' => ['new Module.Event', 'Create scheduled event and handler', 'application/jobs'],
+        'constant' => ['new Module.Constant', 'Create a string constant', 'domain/constants'],
+        'integration' => ['new Module.Adapter', 'Create integration adapter flow', 'infrastructure/integrations'],
+        'published-rest' => ['new Module.Handler', 'Create published REST handler flow', 'infrastructure/endpoints'],
+        'consumed-rest' => ['new Module.Client', 'Create consumed REST adapter flow', 'infrastructure/integrations'],
+        'java-action' => ['new Module.Adapter', 'Create Java Action adapter flow', 'infrastructure/actions'],
+        'design' => ['init', 'Initialize the project design system', 'app/design_system'],
+        'ci' => ['init github', 'Create a GitHub Actions workflow', '.github/workflows']
+      }.freeze
+      OPTIONS = <<~HELP
+        Options:
+          --target DIR   Project root (default: current directory)
+          --dry-run      Preview paths and aggregator updates without writing
+          --json         Render the result as JSON
+          --help         Show this help
+
+        Documentation:
+          https://github.com/lucamykael/mxrb/blob/main/docs/pt-BR/scaffolds.md
+      HELP
+      PAGE_OPTIONS = <<~HELP
+        Page chains:
+          --chain page:microflow           Page calls a microflow directly
+          --chain page:nanoflow             Page calls a client nanoflow
+          --chain page:nanoflow:microflow   Page calls a nanoflow that calls a microflow
+
+        Without --chain, creates the minimal page scaffold.
+
+        Page templates:
+          mxrb page templates [--json]
+          --template starter|blank|dashboard|form-vertical
+      HELP
+
+      def text(command)
+        usage, description, destination = COMMANDS.fetch(command)
+        <<~HELP
+          Usage: mxrb #{command} #{usage} [--target DIR]
+
+          #{description}.
+          Destination: #{destination}
+          Existing files are never overwritten. Aggregators are connected automatically.
+
+          #{page_options(command)}
+
+          #{OPTIONS}
+        HELP
+      end
+
+      def page_options(command)
+        return '' unless command == 'page'
+
+        PAGE_OPTIONS
+      end
+    end
+  end
+end

data/lib/mxrb/scaffold/page_templates.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Mxrb
+  module Scaffold
+    # Audited page patterns that become ordinary editable Mendix pages.
+    module PageTemplates
+      module_function
+
+      Entry = Data.define(:category, :name, :description, :data_backed)
+      ENTRIES = [
+        Entry.new('General', 'starter', 'Title and page header', false),
+        Entry.new('General', 'blank', 'Empty responsive content area', false),
+        Entry.new('Dashboards', 'dashboard', 'Header and three responsive cards', false),
+        Entry.new('Forms', 'form-vertical', 'DataView with vertical inputs and actions', true)
+      ].freeze
+
+      def fetch(name)
+        return unless name
+
+        ENTRIES.find { _1.name == name.to_s } || raise(
+          ArgumentError, "page template must be one of: #{ENTRIES.map(&:name).join(', ')}"
+        )
+      end
+
+      def tree
+        groups = ENTRIES.group_by(&:category).to_a
+        lines = ['Page templates'] + groups.flat_map.with_index do |group, index|
+          category_lines(group, last: index == groups.size - 1)
+        end
+        lines.join("\n")
+      end
+
+      def category_lines(group, last:)
+        category, entries = group
+        heading = "#{last ? '└──' : '├──'} #{category}"
+        children = entries.map.with_index do |entry, index|
+          branch = index == entries.size - 1 ? '└──' : '├──'
+          "#{last ? '    ' : '│   '}#{branch} #{entry.name} — #{entry.description}"
+        end
+        [heading, *children]
+      end
+
+      def payload
+        ENTRIES.group_by(&:category).map do |category, entries|
+          {
+            category:, templates: entries.map do |entry|
+              { name: entry.name, description: entry.description, data_backed: entry.data_backed }
+            end
+          }
+        end
+      end
+    end
+  end
+end