mxrb 0.1.0

data/docs/en-US/ruby-first-roadmap.md

@@ -0,0 +1,186 @@
+# MXRB: Ruby above all
+
+[Português](../pt-BR/ruby-first-roadmap.md) · **English** · [Deutsch](../de-DE/ruby-first-roadmap.md)
+
+## Architectural principle
+
+Ruby is MXRB's only public language.
+
+- Mendix models are read, created, changed and analyzed through Ruby APIs and DSLs.
+- The CLI is a thin layer over those APIs.
+- MXRB will not introduce MDL or a competing parser/language.
+- Structures without a concise high-level API remain losslessly preserved and
+  editable through generated `native_unit` Ruby hashes.
+- Studio Pro and MxBuild are important external validators, not dependencies of
+  the Ruby core.
+
+## Available capabilities
+
+- Deep MPR v1/v2 reading and writing.
+- Export to editable Ruby projects.
+- Generation, integrity validation and structural comparison.
+- Semantic indexing of modules, entities, members and documents.
+- References, callers, callees and transitive impact queries.
+- Safe model-wide rename with preview.
+- Static analysis of cycles, missing targets and module coupling.
+- Typed semantic diff.
+- Search, description and structural tree navigation.
+- Executable Ruby model evaluations with severity and scores.
+- Functional microflow tests without JUnit.
+- Local or Docker execution of `mx check`, portable MxBuild and Runtime.
+- A native coverage gate: 100% lines and 100% branches in CI, with a
+  stricter 100/100 local default when thresholds are omitted.
+
+## Semantic API
+
+```ruby
+Mxrb.open("app.mpr") do |project|
+  order = project.find_artifact("Sales.Order")
+  refs = project.references_to(order)
+  callers = project.callers_of("Sales.Recalculate")
+  callees = project.callees_of("Sales.Checkout")
+  impact = project.impact_of("Sales.Order")
+end
+```
+
+Results are immutable Ruby objects: `Mxrb::Semantic::Artifact`,
+`Mxrb::Semantic::Reference` and `Mxrb::Semantic::Impact`.
+
+Writable projects persist a fingerprinted semantic-index cache in the MPR.
+Read-only opens may reuse that cache but never modify the project.
+Use `mxrb cache status`, `warm` and `clear` for metrics and maintenance; writes
+use an upsert before stale-entry cleanup so readers never observe an empty
+replacement window.
+
+Exact native Mendix 5 validation remains dependent on Windows/Studio Pro. It
+is documented as a remote legacy limitation and is not a current delivery
+gate.
+
+Navigation profiles now read and write native Mendix navigation documents,
+including role homes and recursive menus. Theme and source assets round-trip
+through a checksum manifest; design-system tokens support inventory, lint,
+contrast metrics and preview-first literal migration.
+
+## Safe rename
+
+```ruby
+Mxrb.open("app.mpr", readonly: false) do |project|
+  plan = project.plan_rename("Sales.Order", to: "Invoice")
+  plan.changes.each { puts _1.inspect }
+  plan.apply!
+end
+```
+
+The CLI previews by default; `--apply` is required to write.
+
+## Safe removal
+
+Standalone units such as microflows and pages can be inspected before removal:
+
+```ruby
+Mxrb.open("app.mpr", readonly: false) do |project|
+  plan = project.plan_remove("Sales.UnusedFlow")
+  plan.apply! if plan.safe?
+end
+```
+
+The plan is blocked while incoming references or child units exist. Embedded
+domain-model elements require their typed domain-model mutation instead. The
+CLI follows the same rule: `mxrb remove app.mpr Sales.UnusedFlow` previews and
+`--apply` writes only a safe plan.
+
+## Safe same-module move
+
+Standalone units can move to a module or folder without changing their
+qualified name or references:
+
+```ruby
+Mxrb.open("app.mpr", readonly: false) do |project|
+  plan = project.plan_move("Sales.Process", to: "Sales.Automation")
+  plan.apply!
+end
+```
+
+The plan preserves the native containment type and blocks embedded
+domain-model elements, non-container targets, folder cycles and cross-module
+moves. `mxrb move app.mpr Sales.Process Sales.Automation` previews the exact
+container IDs; `--apply` performs the transaction.
+
+## Static analysis
+
+```ruby
+report = Mxrb.open("app.mpr", &:analyze)
+report.errors.each { warn _1.message }
+report.call_cycles.each { puts _1.artifacts.map(&:qualified_name) }
+```
+
+Absent targets in an existing module are errors. External contracts are
+warnings, and `System.*` references are recognized as platform references.
+
+## Typed diff and navigation
+
+```ruby
+result = Mxrb.diff("before.mpr", "after.mpr")
+result.added.each { puts _1.path }
+project.search_artifacts("checkout", kind: :microflow)
+project.describe_artifact("Sales.Checkout")
+```
+
+CLI equivalents include `diff`, `find`, `describe` and `tree`.
+
+## Model evaluations
+
+```ruby
+result = Mxrb.open("app.mpr") do |project|
+  project.evaluate do
+    artifact "Sales.Order", kind: :entity
+    no_call_cycles
+    no_missing_internal_references
+    maximum_unreferenced 20, severity: :warning
+  end
+end
+```
+
+Evaluation files are ordinary Ruby and run with
+`mxrb evaluate app.mpr evaluation.rb`.
+
+## Official Mendix Marketplace
+
+This command family remains separate from `mxrb module`. It integrates the
+documented Marketplace Content API for authenticated search, metadata,
+compatible versions, direct download, private company content, and security
+auditing. GitHub releases and local MPK import remain fallback routes.
+
+Local MPKs are imported directly into the target MPR through Ruby/SQLite/BSON,
+including the complete unit tree and declared assets, without Mendix tools.
+The PAT requires `mx:marketplace-content:read`. Official downloads are selected
+against the target MPR version, vulnerable releases are denied by default, and
+Content/Version IDs plus security metadata are written to the lockfile.
+Authenticated Kafka acceptance and transactional lifecycle are now delivered.
+`marketplace update` and `marketplace remove` preview by default, preserve
+externally referenced IDs, reject changed assets, and snapshot MPR,
+`mprcontents`, cache, lock, and assets before explicit `--apply`. Remaining
+authenticated work is also delivered: `marketplace dependencies` recursively
+resolves official packages from references in the embedded MPR, verifies each
+downloaded MPK's actual module identity, recognizes host-owned modules, applies
+leaf-first, and rolls back atomically. Kafka package graphs passed authenticated
+10.24 and 11.12 acceptance, and imported modules now export to Ruby and rebuild
+with asset checksums and source/rebuild diagnostics preserved.
+
+The authenticated matrix now includes DataWidgets 3.11.3 (Content ID 116540,
+Version ID `e7b6d703-8e47-42f4-bb92-934e3601e71b`) and the independent official
+Combo box Widget/clientModule component 219304, version 2.9.0, Version ID
+`dce845f4-d051-4161-847c-016c01703caa`. Combo installation backs up and
+replaces the 2.6.x asset previously owned by Atlas Core (Content ID 117187).
+Ruby round trips preserve Marketplace lock/cache/original provenance, and
+`script/frontend_acceptance` fails on model, asset, checksum, or provenance
+drift. Native renderer coverage for the accepted 10.24 and 11.12 fixtures has
+zero source and rebuilt preflight findings.
+
+The migration interface is delivered as `mxrb frontend migrate FILE.mpr`: it
+previews by default and writes a safe transactional plan only with `--apply`.
+That migration track is complete across the supported frontend matrix. The
+optional external MxBuild oracle returns zero errors for source and rebuild on
+10.24 and 11.12; `mx check` also preserves byte-identical observable package
+diagnostics across each round trip. MXRB remains independent: `mx` and MxBuild
+are validation oracles only, never generators, mutators, or runtime dependencies.

data/docs/en-US/scaffolds.md

@@ -0,0 +1,57 @@
+# Project scaffolds
+
+[Português](../pt-BR/scaffolds.md) · **English** · [Deutsch](../de-DE/scaffolds.md)
+
+Every command accepts `--target DIR`, refuses to overwrite files, and wires
+`evaluate`/`evaluate_dir` aggregators automatically. Run
+`mxrb <command> --help` for usage, destination, and options.
+
+The available families are project/module (`init`, `module new`), domain
+(`entity`, `enumeration`, `constant`), application (`use-case`, `validation`,
+`query`, `repository`, `scheduled-event`), presentation (`presentation init`,
+`page`, `nanoflow`), security, infrastructure (`integration`, `published-rest`,
+`consumed-rest`, `java-action`), verification (`functional-test`, `evaluation`),
+design, and GitHub CI. `mxrb page new Module.Page` keeps creating a minimal
+page. Adding `--chain` creates an executable vertical slice with a sample
+entity, data-source microflow, editable page, actions, and a Responsive
+navigation item. Three real Mendix action chains are available:
+
+```sh
+mxrb page new App.Order --chain page:microflow
+mxrb page generate App.Order --chain page:nanoflow
+mxrb page g App.Order --chain page:nanoflow:microflow
+```
+
+`page:microflow` calls the Runtime directly; `page:nanoflow` keeps the action
+client-side; and `page:nanoflow:microflow` uses the client flow to orchestrate a
+Runtime call. All modes create `ACT_LoadOrder` for the data source. Chains that
+end in a microflow also create `ACT_RefreshOrder`. `page generate` and `page g`
+are aliases of `page new`. Every generated chain is materialized as a valid MPR
+and checked by compiler preflight.
+
+## Page templates
+
+In Mendix, page templates are starting points whose structure becomes a normal,
+editable page. MXRB lists only patterns audited by its compiler and Runtime:
+
+```sh
+mxrb page templates
+mxrb page templates --json
+mxrb page new App.Landing --template starter
+mxrb page new App.Empty --template blank
+mxrb page new App.Operations --template dashboard
+mxrb page new App.Order_NewEdit --template form-vertical
+```
+
+`form-vertical` also creates a sample entity and `ACT_Load...` DataView source.
+Every template can be combined with `--chain`; for example,
+`--template dashboard --chain page:nanoflow` adds a client action to the
+dashboard. These names are stable MXRB contracts inspired by Mendix patterns,
+not a claim that every installed Atlas or Marketplace template is silently
+imported. See the [official pages documentation](https://docs.mendix.com/refguide/pages/).
+
+Artifact commands use `new Module.Name`; project commands use `design init` and
+`ci init github`. See the [entity DSL](entity-dsl.md) for all supported entity
+types and associations. Published REST and Java Action create editable Ruby
+adapters; their native document/action must still come from an exported
+baseline or Studio Pro.

data/docs/en-US/semantic-refactoring.md

@@ -0,0 +1,198 @@
+# Semantic refactoring
+
+[Português](../pt-BR/semantic-refactoring.md) · **English** · [Deutsch](../de-DE/semantic-refactoring.md)
+
+MXRB renames, removes, moves, extracts and inlines artifacts directly in
+Ruby — no Studio Pro, no MDL. Every operation follows the same
+plan / preview / `apply!` pattern described in
+[architectural patterns](architectural-patterns.md): build a plan, inspect
+its changes, then write inside a transaction.
+
+All examples assume a writable project:
+
+```ruby
+Mxrb.open("app.mpr", readonly: false) do |project|
+  # plans below
+end
+```
+
+The CLI equivalents preview by default and require `--apply` to write.
+
+## Finding artifacts and references first
+
+Refactoring decisions start from the semantic index:
+
+```ruby
+project.find_artifact("Sales.Order", kind: :entity)
+project.search_artifacts("order", kind: :microflow)
+project.semantic_search_artifacts("create a customer order", limit: 5)
+project.references_to("Sales.Order")
+project.references_from("Sales.Order_Overview")
+project.callers_of("Sales.Recalculate")
+project.callees_of("Sales.Checkout")
+project.impact_of("Sales.Order").artifacts
+```
+
+`impact_of` is transitive by default; pass `transitive: false` for direct
+dependents only. CLI: `mxrb find`, `mxrb refs`, `mxrb callers`,
+`mxrb callees`, `mxrb impact`.
+
+Semantic search always has a deterministic Ruby backend. Installing the
+optional `sqlite-vec` gem enables a fingerprinted KNN cache inside writable
+MPRs; read-only projects and platforms without the native extension keep the
+same API and rank in memory. The first accelerated call populates the vector
+table before recording its backend, dimension and model fingerprint, so an
+empty or stale index is never treated as ready.
+Use `mxrb find app.mpr "customer order" --semantic` for the legacy adapter.
+The dedicated command also exposes the backend, result limit, and cosine
+distance:
+
+```sh
+bundle exec mxrb search "payment" App.mpr
+bundle exec mxrb search "create order" App.mpr --backend onnx --limit 5
+```
+
+Tabular output contains rank, distance, qualified name, and kind; `--json`
+provides the same fields for automation.
+
+For local ONNX development, enable the optional dependency group with
+`BUNDLE_WITH=onnx bundle install`. `backend: :onnx` and the automatic backend
+then use Informers' documented `embedding` pipeline with
+`sentence-transformers/all-MiniLM-L6-v2`. CI sets `MXRB_ONNX=1` in its
+dedicated job and runs a real 384-dimensional model smoke test; ordinary test
+and gem installations do not download the model.
+
+The native sqlite-vec smoke test uses its own supported-platform dependency
+file: `BUNDLE_GEMFILE=Gemfile.sqlite-vec bundle install`, followed by
+`MXRB_SQLITE_VEC=1 BUNDLE_GEMFILE=Gemfile.sqlite-vec bundle exec rspec
+spec/semantic_search_spec.rb`. This keeps unsupported architectures out of the
+main lockfile while CI still exercises the actual extension.
+
+## Rename
+
+```ruby
+plan = project.plan_rename("Sales.Order", to: "Invoice")
+plan.changes.each { puts "#{_1.path.join(".")}: #{_1.before} -> #{_1.after}" }
+plan.apply!
+# or in one step: project.rename!("Sales.Order", to: "Invoice")
+```
+
+The plan rewrites the declaration and deep references across the model,
+including Mendix member paths such as `Sales.Order/Number`. It validates name
+rules, qualification depth, collisions and container legality before writing.
+
+```sh
+bundle exec mxrb rename app.mpr Sales.Order Invoice --apply
+```
+
+## Remove
+
+```ruby
+plan = project.plan_remove("Sales.UnusedFlow")
+plan.apply! if plan.safe?
+```
+
+Removal is blocked while incoming references or child units exist, and a plan
+cannot be applied twice. Embedded domain-model elements (entity, attribute,
+association) are not standalone units — use the typed domain mutations below
+instead.
+
+```sh
+bundle exec mxrb remove app.mpr Sales.UnusedFlow --apply
+```
+
+## Move
+
+```ruby
+plan = project.plan_move("Sales.Process", to: "Sales.Automation")
+plan.apply!
+```
+
+A same-module move changes the unit's container (module folder) while
+preserving its qualified name, so references stay intact. Folder cycles,
+embedded elements and non-container targets are rejected. Cross-module moves
+compose the move with a rename so calls, security, pages and contracts are
+updated atomically; both directions are validated on MPR v1 and v2.
+
+```sh
+bundle exec mxrb move app.mpr Sales.Process Sales.Automation --apply
+```
+
+## Extract a submicroflow
+
+`plan_extract` lifts a subgraph of activities into a new submicroflow and
+patches the source with a call to it:
+
+```ruby
+plan = project.plan_extract("Sales.CreateOrder",
+                            as: "Sales.Validate",
+                            object_ids: [first_activity_id, second_activity_id])
+plan.apply!
+```
+
+Extraction requires the source to be a microflow in the same module, a free
+target name, existing activity IDs that are not start/end events, and exactly
+one entry point and one exit point in the selected subgraph.
+
+## Inline a called microflow
+
+`plan_inline` is the inverse: it replaces a `call_microflow` activity with
+the callee's own activities, remapping object UUIDs so nothing collides with
+the caller:
+
+```ruby
+plan = project.plan_inline("Sales.CreateOrder", calling: "Sales.Validate")
+plan.apply!
+```
+
+## Domain-model mutation
+
+Entities and attributes are embedded in the domain model, so they have typed
+mutations of their own:
+
+```ruby
+project.plan_add_entity("Sales", name: "Invoice").apply!
+project.plan_add_attribute("Sales.Invoice", name: "Number", type: :string,
+                           required: true).apply!
+project.plan_change_attribute("Sales.Invoice.Number", length: 40).apply!
+project.plan_remove_attribute("Sales.Invoice.Number").apply!
+project.plan_remove_entity("Sales.Invoice").apply!
+```
+
+Each has a bang convenience form (`add_entity!`, `add_attribute!`, ...).
+
+## Batch plans
+
+Several plans can be previewed and applied as one unit:
+
+```ruby
+batch = project.batch_plan([
+  project.plan_rename("Sales.Order", to: "Invoice"),
+  project.plan_move("Sales.Process", to: "Sales.Automation")
+])
+batch.apply!
+```
+
+## Static analysis alongside refactoring
+
+`project.analyze` (aliased as `lint`) reports missing internal references,
+external contracts, call cycles, unreferenced artifacts and module coupling,
+and accepts custom Ruby rules:
+
+```ruby
+report = project.analyze(rules: [my_rule])
+report.errors.each { warn _1.message }
+```
+
+CLI: `mxrb lint app.mpr` and `mxrb report app.mpr`.
+
+## Structural version migration
+
+For projects generated by MXRB (which store their architecture definition in
+the MPR), `migrate_to!` re-runs the writer with a different Mendix version so
+every version-specific BSON structure is regenerated correctly. It is
+idempotent and also aliased as `upgrade_to!` / `downgrade_to!`:
+
+```ruby
+project.migrate_to!("11.12.1")
+```

data/docs/en-US/team-server.md

@@ -0,0 +1,32 @@
+# Team Server
+
+MXRB connects directly to official Team Server Git repositories and the App
+Repository API without `mx`, Studio Pro, or the Model SDK:
+
+```sh
+mxrb team-server login --pat-file /secure/team-server.env
+mxrb team-server projects --pat-file /secure/team-server.env
+mxrb team-server clone APP_ID ./app
+mxrb team-server branches APP_ID
+mxrb team-server pull ./app
+```
+
+`projects` paginates the official Projects API and returns every company-owned
+project. Credentials remain scoped to the same HTTPS host; the client upgrades
+the service's advertised HTTP redirect only when it targets that same HSTS host.
+
+The recommended mode stores only the absolute PAT file path. Plain text, JSON,
+and `.env` files containing `MXRB_TEAM_SERVER_PAT` are supported. The PAT is
+read only for requests and passed to Git through a temporary `GIT_ASKPASS`
+helper; it is never embedded in URLs, arguments, or `.git/config`.
+
+Read requires `mx:modelrepository:repo:read`; push also requires
+`mx:modelrepository:repo:write`. Mendix documents that external clones do not
+receive all Studio Pro post-processing and revision metadata. MXRB validates
+root MPR files after clone and pull, but cannot manufacture Mendix Cloud
+revision metadata.
+
+The repository `a9e4af8a-2776-4b10-a471-8c42df8f5f43` was queried through the
+App Repository API and cloned over HTTPS. MXRB validated `MyFirstModule.mpr`,
+detected `main`, and confirmed that the remote URL contained no PAT. The
+temporary acceptance credential file was destroyed afterwards.