mxrb 0.1.2 → 0.1.4

data/docs/en-US/project-structure.md

@@ -2,8 +2,18 @@
 
 [Português](../pt-BR/project-structure.md) · **English** · [Deutsch](../de-DE/project-structure.md)
 
-The Ruby tree produced by `mxrb export` separates app-wide policy, module
-behavior, preserved native units and filesystem assets:
+`mxrb export` has two explicit modes. `--mode mendix` is the default and keeps
+the layered Mendix DSL tree. `--mode ruby` creates a conventional executable
+Ruby application with a React + Vite frontend.
+
+## Mendix mode
+
+```sh
+bundle exec mxrb export App.mpr app-source --mode mendix
+```
+
+This tree separates app-wide policy, module behavior, preserved native units
+and filesystem assets:
 
 ```text
 project.rb
@@ -46,4 +56,184 @@ The same tree supports all four normal workflows:
 - Mendix project to editable Ruby;
 - Mendix export to Ruby and back to a structurally equivalent Mendix project.
 
+## Ruby mode
+
+Ruby mode can also start without an existing Mendix project:
+
+```sh
+bundle exec mxrb init CustomerPortal --mode ruby
+cd CustomerPortal
+bundle install
+npm install --prefix frontend
+bundle exec mxrb run .
+```
+
+This creates the conventional application directly with `app/models`,
+`app/dtos`, `app/services`, `app/pages`, and React + Vite. A reversible Mendix
+baseline is isolated under `.mxrb`; it does not dictate the editable source
+layout. Materialize the current project as an MPR with:
+
+```sh
+bundle exec mxrb generate project.rb build/CustomerPortal.mpr
+```
+
+New Ruby models become entities, DTOs become non-persistent entities, and the
+bidirectional declarations are synchronized into the MPR. Ruby or React code
+without a native Mendix representation remains checksum-embedded and returns
+unchanged on the next export. Compilation fails explicitly when a structural
+change cannot be represented, preventing a silent partial conversion.
+
+To convert an existing MPR, use:
+
+```sh
+bundle exec mxrb export App.mpr app-ruby --mode ruby
+```
+
+```text
+app/
+  models/
+  dtos/
+  services/
+  pages/
+config/application.rb
+frontend/
+  package.json
+  vite.config.ts
+  tsconfig.json
+  src/{main.tsx,App.tsx,types.ts,nanoflows.ts,app.css}
+project.rb
+.mxrb/
+  ruby-app.json
+  runtime/App.mpr
+  mendix/
+```
+
+Persistent entities become records. Non-persistent entities become DTO classes
+and always use the `_dto.rb` suffix, avoiding ambiguous `_2.rb` names. Services
+are ordinary Ruby classes and initially delegate to the pure-Ruby native
+interpreter. Pages expose native metadata to the React + TypeScript frontend.
+The export derives `types.ts` from entities, enumerations, pages, widgets,
+contexts, effects, and API contracts; `npm run typecheck` is part of the Vite build.
+
+Install the Ruby and frontend dependencies once, then start both processes with
+one command:
+
+```sh
+bundle install
+npm install --prefix frontend
+bundle exec mxrb run .
+```
+
+`mxrb run` supervises the loopback Ruby JSON API, served by Puma 8, and the
+Vite development server.
+Vite proxies `/api` to Ruby. Use `--server-port` for the backend port and
+`--client-port` for the frontend port. `--no-frontend` starts only the API.
+The former `--api-port` and `--port` names remain compatibility aliases.
+The global `--no-progress` option is optional and only hides progress output.
+
+Two opt-in stacks add familiar Ruby conventions without changing the default
+Ruby mode:
+
+```sh
+bundle exec mxrb init ServiceDesk --mode ruby --flymetothemoon
+bundle exec mxrb export App.mpr app-rails --mode ruby --onrails
+```
+
+`--flymetothemoon` adds Sinatra, Puma, ActiveRecord, Rake and RSpec.
+`--onrails` adds Rails, Puma, ActiveRecord and RSpec. Both keep React + Vite as
+the integrated application frontend and run through the same `mxrb run .`
+command. ActiveRecord migrations own Ruby-only tables; the MXRB manifest stays
+authoritative for the Mendix domain model and its round-trips.
+
+## Browser domain-model diagram
+
+Open one or more Mendix module domain models in a DBeaver-inspired ER diagram:
+
+```sh
+bundle exec mxrb diagram-er App.mpr --module Sales
+bundle exec mxrb diagram-er App.mpr --module Sales --module Billing \
+  --output build/App-layout.mpr
+```
+
+The sidebar can select several modules together and displays associations
+between them. The browser also supports entity search, drag-and-drop
+positioning, zoom, fit, auto-arrange, grid, attribute visibility, relationship
+routing and draggable source/target anchors. Persistent entities are blue,
+DTO/non-persistent entities yellow, and OQL views green. **Save layout to MPR**
+writes positions and local-association anchors to native Mendix fields;
+cross-module anchors, which have no native BSON field, use isolated MXRB visual
+metadata in the same safe copy. The default copy is `App.domain-layout.mpr`; an
+existing output requires `--force`.
+
+**Export PNG** downloads a high-resolution image of the selected modules using
+the current colors, attributes and routes. PNG export does not modify the MPR;
+save the layout separately when those positions must survive a round-trip.
+
+Foreground mode remains available and occupies the terminal until `Ctrl+C`.
+Use the managed lifecycle to keep the ER editor in the background; stopping it
+preserves the layout copy and neither the source MPR nor its files are edited or
+removed:
+
+```sh
+bundle exec mxrb diagram-er up App.mpr --module Sales
+bundle exec mxrb diagram-er status App.mpr
+bundle exec mxrb diagram-er down App.mpr
+bundle exec mxrb diagram-er up App.mpr       # resume the same copy
+bundle exec mxrb diagram-er destroy App.mpr --yes
+```
+
+`destroy` stops the server and removes only the copy and external contents
+created by that lifecycle. Management uses a private authenticated loopback
+endpoint; state and token are stored in permission-restricted local files.
+
+The editor UI is implemented in React + TypeScript and talks only to the Ruby
+server APIs. Its Vite bundle is compiled into `lib/mxrb/web_ui`, included in the
+gem, and served locally. Node.js is therefore not required to use the installed
+editor, and no CDN is contacted. To develop the UI, run `npm install`,
+`npm run typecheck`, and `npm run build` from `frontend/modeler`.
+ER, UML, OQL, and the generic `--mode ruby` backend share the same embedded
+Puma adapter. `puma ~> 8.0` is a direct MXRB dependency and brings
+`nio4r ~> 2.0` transitively; WEBrick is not part of the HTTP stack.
+
+## UML diagrams
+
+UML is an additional implementation independent from the ER editor. It uses
+port 4569 and does not change domain-model layout. The viewer combines class,
+microflow activity and call-sequence diagrams rendered with Mermaid:
+
+The same server publishes `http://127.0.0.1:4569/modeler`, a React + TypeScript
+visual catalog for modules, pages, microflows and nanoflows, navigation,
+security, integrations, and settings. This first expanded surface is read-only;
+mutations remain locked until they have fail-closed validation and round-trip
+guarantees equivalent to the ER editor.
+
+```sh
+bundle exec mxrb uml App.mpr
+bundle exec mxrb uml App.mpr --export=class --module Sales
+bundle exec mxrb uml App.mpr --export=activity \
+  --microflow=Sales.CreateOrder --format=plantuml
+bundle exec mxrb uml App.mpr --export=sequence \
+  --root=Sales.CreateOrder --depth=3
+bundle exec mxrb uml App.mpr --export=sequence --module=Sales
+```
+
+Without `--export`, the unified viewer is served at
+`http://127.0.0.1:4569`. Text export defaults to Mermaid; select PlantUML with
+`--format=plantuml`. Sequence diagrams accept either a depth-limited root or
+all calls internal to one module. The viewer uses the same React + TypeScript
+workspace, with Mermaid bundled locally so rendering also works offline.
+
+## Version transitions and round-trips
+
+Both modes retain the stable Mendix IDs and complete native baseline required
+for upgrades, downgrades and repeated round-trips. In Ruby mode, model/DTO
+declarations are reverse-compiled into the MPR. Ruby service bodies and React
+sources are stored with SHA-256 checksums in the MXRB source table inside the
+MPR, so a later `--mode ruby` export restores the exact edited files.
+
+Native Mendix behavior remains authoritative for constructs with no semantic
+Ruby-to-Mendix compiler yet; the coverage manifest records that status instead
+of silently claiming a conversion. The preserved Ruby/React source survives a
+Mendix round-trip even when it has no direct Studio Pro representation.
+
 [Back to the documentation index](README.md)

data/docs/en-US/runtime-ruby.md

@@ -0,0 +1,100 @@
+# Java-free runtime
+
+Ruby mode runs the backend without starting the Mendix Java Runtime. When an
+exported application opens, MXRB automatically migrates an environment-specific
+SQLite database, opens the microflow interpreter, registers lifecycle hooks,
+enforces security, and starts scheduled events.
+
+Profiles live under `config/environments/` and commonly use `development.env`,
+`qa.env`, `staging.env`, and `production.env`. Precedence is process environment,
+profile file, `.env.<profile>`, then `.env`. Select one with `--environment qa`
+or `MXRB_ENV=qa`; `mxrb env . --environment qa` shows sources and key names but
+never values.
+
+```bash
+mxrb run . --environment qa
+mxrb test App.mpr smoke.rb --native --environment qa
+```
+
+Each profile defaults to `.mxrb/runtime/<environment>.sqlite3`. Schema migration
+derives entities, attributes, associations, and system members; additive changes
+are idempotent and incompatible changes use a transactional rebuild. Non-
+persistent entities remain in memory.
+
+The Ruby API provides login and bearer tokens, sessions, schema, navigation,
+pages, microflows, CRUD, and published REST. Page and microflow roles, entity
+access rules, member rights, and the safe XPath subset are enforced for every
+request. Credentials come from `MXRB_USERS_JSON` and `MXRB_AUTH_TOKENS` and
+should be supplied by ignored local files or the deployment secret manager.
+
+Scheduled events use MXRB's stdlib scheduler with minute, hour, and day
+intervals, overlap protection, and supervised shutdown. IANA time zones such
+as `America/New_York` use `tzinfo`, including daylight-saving transitions.
+Unknown zones fail during scheduling instead of silently falling back to UTC;
+`UTC`, `local`, and numeric offsets such as `-04:00` are also supported.
+
+Sessions and scheduler coordination default to the native shared SQLite file
+`.mxrb/runtime/<environment>-shared.sqlite3`, with no external service. Multiple
+instances must point `MXRB_SHARED_STORE_PATH` to the same file. Idempotent
+event-slot claims and heartbeat-renewed overlap leases are atomic; an unfinished
+claim can be recovered after its lease expires. The default lease is 300 seconds
+and can be changed with `MXRB_SCHEDULER_LEASE_TTL`. Set the shared-store path to
+`:memory:`, `memory`, or `local` for explicit process-local mode.
+
+Java Custom Actions never start a JVM. Every permitted action must have an
+explicit Ruby adapter registered by qualified name in `config/adapters.rb`:
+
+```ruby
+Mxrb::RubyApp::Registry.register_java_custom_action('Orders.CalculateTotal') do |arguments|
+  Calculator.call(
+    items: arguments.fetch('Items'),
+    discount: arguments.fetch('Discount')
+  )
+end
+```
+
+Keys are the parameter names from the Mendix model. Basic values are evaluated
+in the microflow context; entity, microflow, and mapping references are passed
+as qualified names. The return value is assigned only when `UseReturnVariable`
+is enabled (or for the legacy shape that only declares `ResultVariableName`).
+An unregistered action fails closed with its name and registration guidance;
+there is no class discovery, JAR execution, or JVM fallback. REST, app services,
+SOAP, mappings, and document generation continue to use type-level Ruby
+adapters. The browser still runs JavaScript/React, while its backend and APIs run
+without the Java Runtime.
+
+## Ruby → Mendix → Ruby certification
+
+The reproducible certification scenario lives in
+[`spec/fixtures/flymetothemoon/project.rb`](../../spec/fixtures/flymetothemoon/project.rb).
+It models customers, products, orders, and order lines in Ruby, including an
+enumeration, indexes, associations, microflows, a nanoflow, a scheduled event,
+and a data-grid page. The
+[`spec/flymetothemoon_roundtrip_spec.rb`](../../spec/flymetothemoon_roundtrip_spec.rb)
+test verifies these use cases:
+
+- generate and validate a Mendix 11.12.1 MPR from the Ruby DSL;
+- export through the real CLI with `--mode ruby --flymetothemoon`;
+- require Sinatra, Puma, ActiveRecord, and RSpec while producing no Java, JAR,
+  or bytecode files;
+- execute creation, aggregation, branching, CRUD, and page metadata through the
+  Ruby Runtime and SQLite;
+- compile an unchanged app and structurally compare the MPR with its source;
+- add an attribute and replace a microflow with idiomatic Ruby;
+- export once more and prove that both the Ruby code and Mendix model survive a
+  second structurally identical round trip.
+
+Run the isolated case with:
+
+```bash
+bundle exec rspec spec/flymetothemoon_roundtrip_spec.rb
+```
+
+For generated interfaces, the declarative
+[`spec/fixtures/frontend_browser/sudoku_full_flow.json`](../../spec/fixtures/frontend_browser/sudoku_full_flow.json)
+scenario runs through `script/frontend_browser_acceptance` in a real Chromium.
+It covers board positions 73 and 74, selection, value entry, and Easy, Medium,
+and Hard transitions. Each critical click waits for the microflow POST plus the
+association GET and must finish within 250 ms. Gallery queries are filtered by
+context in SQLite; objects loaded through an inverse association retain that
+link when only attributes are committed.

data/docs/en-US/runtime-schema-migrations.md

@@ -0,0 +1,41 @@
+# Ruby runtime schema migrations
+
+`Mxrb::Runtime::SchemaMigrator` identifies Mendix entities, attributes, and
+associations by storage GUID. Renaming an artifact while preserving its GUID
+keeps the physical table or column and its data.
+
+## Safe policy
+
+- Creating tables and adding optional attributes is automatic and idempotent.
+- Required attributes are emitted as `NOT NULL`.
+- Making an existing attribute required rebuilds the table transactionally.
+  Existing `NULL` values use the declared default; without a default, the
+  migration is rejected.
+- Adding a required attribute to a populated table requires a default.
+- Compatible changes preserve entity and association rows.
+- Removing an entity, attribute, or association raises
+  `Mxrb::Runtime::UnsafeSchemaMigrationError` by default and leaves the
+  database unchanged.
+- After reviewing the plan and taking a backup, destructive cleanup can be
+  enabled with `allow_destructive: true`. Only artifacts recorded in MXRB
+  metadata are removed; unrelated tables are never inferred or deleted.
+
+Exported Ruby applications keep destructive migration disabled. For a
+controlled run after backup, set
+`MXRB_ALLOW_DESTRUCTIVE_MIGRATIONS=true` in the selected environment profile.
+Every other value remains fail-closed.
+
+```ruby
+database = SQLite3::Database.new('runtime.sqlite3')
+migrator = Mxrb::Runtime::SchemaMigrator.new(
+  project,
+  database: database,
+  allow_destructive: true
+)
+result = migrator.migrate!
+puts migrator.migration_plan.changes
+```
+
+DDL, data copying, metadata updates, and authorized cleanup share one SQLite
+transaction. Any constraint violation or other failure rolls back the complete
+migration.

data/docs/en-US/validation-matrix.md

@@ -2,7 +2,7 @@
 
 [Português](../pt-BR/validation-matrix.md) · **English** · [Deutsch](../de-DE/validation-matrix.md)
 
-Last updated: 2026-08-05.
+Last updated: 2026-08-11.
 
 The matrix exercises this pipeline using only MXRB:
 
@@ -27,6 +27,23 @@ are never modified.
 | `mendixlabs/TreeViewAndGridView` (`TreeviewDemo`) | 5.21.4 | v1 | 176 | pass |
 | `mendixlabs/TreeViewAndGridView` (`GridViewPlayground`) | 6.10.8 | v1 | 122 | pass |
 
+On August 11, `script/validate_matrix` repeated the matrix with **6/6 passes**:
+1,506 units, 1,734 artifacts, and 3,388 references in 16.381 seconds.
+
+## Additional local inventory
+
+`script/certify_mprs --cycles 2 --repair-hashes` certified seven additional
+MPRs through 14 consecutive round trips: **7/7 passes**, 2,799 units, 3,238
+artifacts, and 4,819 references. The set covers LearnNow, SLATaskApp,
+SLATaskAppNative, MyFirstModule, CourseManager, RubyBridgeSandbox, and
+VetClinic.
+
+SLATaskApp had one stale content hash and RubyBridgeSandbox had two. The gate
+repaired only `Unit.ContentsHash` in temporary copies, recorded the changed
+UUIDs, and preserved the original BSON bytes. Source files were not modified.
+The second round trip also exposed and fixed native-widget types deserialized
+as strings.
+
 The comparator used for this matrix includes:
 
 - project metadata and format;
@@ -162,6 +179,24 @@ and is also expanded into editable `native_unit` hashes in
 `.mxrb/native_units.rb`. Concise typed DSLs overlay that complete Ruby
 representation where available.
 
+## Widget certification
+
+`script/certify_widgets --browser-report REPORT.json App.mpr` is the fail-closed
+gate for native web compiler and Marketplace widgets actually used by a
+project. It jointly requires page/layout compilation without fallbacks, resolution of every
+pluggable ID to an MPK `.mjs` entry with SHA-256, a version-owned native Rspack
+build, and passing Chromium evidence that declares every exercised widget type
+and ID without visible Runtime/widget errors.
+
+Importing an MPK or compiling its bundle alone does not certify behavior.
+Widgets that require a datasource, attribute, or specific parent placement only
+pass in a browser scenario configured with that valid context. Future or
+unexercised packages fail as missing evidence instead of inheriting a universal
+compatibility claim.
+The React/TypeScript frontend for `--mode ruby` has a separate track: its
+Chromium report certifies those widgets without claiming that equivalent
+pluggable components also passed in the Mendix Runtime.
+
 ## Ruby semantic index
 
 The Ruby semantic index was built successfully from every original MPR in the
@@ -202,9 +237,9 @@ instead of dumping the complete removed and added flow bodies.
 
 ## Ruby evaluations and coverage gate
 
-The current suite contains 1,039 examples and passes with 100.00% line coverage
-(17,224/17,224 executable library lines) and 100.00% branch coverage
-(6,811/6,811 branches).
+The current suite contains 1,329 examples and passes with 100.00% line coverage
+(23,771/23,771 executable library lines) and 100.00% branch coverage
+(9,704/9,704 branches).
 Run the enforced gate with:
 
 ```sh

data/docs/pt-BR/README.md

@@ -13,6 +13,7 @@
 - [Roadmap Ruby-first](ruby-first-roadmap.md)
 - [Matriz de validação](validation-matrix.md)
 - [Compilador nativo e Runtime](compiler.md)
+- [Runtime Ruby sem Java e ambientes](runtime-ruby.md)
 - [Relatório de qualidade do build e Runtime](native-runtime-quality-report.md)
 - [Criação e edição de projetos](writing.md)
 - [Scaffolds de projeto](scaffolds.md)

data/docs/pt-BR/entity-dsl.md

@@ -94,6 +94,12 @@ entity :AnimalSearchResult do
   string :Name
 end
 
+entity :AnimalSummaryView do
+  oql_view source: "VetClinic.AnimalSummarySource"
+  string :Name
+  integer :Total
+end
+
 entity :Animal do
   before_commit microflow: "VetClinic.VAL_Animal"
   after_commit microflow: "VetClinic.ACT_AfterAnimalCommit"
@@ -111,6 +117,8 @@ end
 
 Em `access_rule`, `read:` e `write:` aceitam `:all`, `:none` ou uma lista de
 atributos. Declare um ou mais papéis qualificados como primeiros argumentos.
+`oql_view` liga a entidade ao `ViewEntitySourceDocument`; ao exportar um projeto
+existente, a consulta OQL aparece junto da entidade em `domain/oql_views`.
 
 Use `mxrb entity --help` para o comando e `mxrb generate project.rb` seguido de
 `mxrb validate App.mpr` para validar o resultado.

data/docs/pt-BR/oql-sql.md

@@ -42,6 +42,47 @@ Os nomes físicos devem ser conferidos no banco criado pelo Runtime Mendix
 exato. Joins por caminho de associação são declarados não suportados enquanto
 os metadados de armazenamento do Runtime não puderem provar o join correto.
 
+## Conversão segura de SQL para OQL
+
+O caminho inverso aceita um subconjunto de `SELECT` em PostgreSQL, SQL Server
+ou ANSI e produz OQL lógico. Informar o projeto permite recuperar exatamente a
+capitalização dos módulos, entidades e atributos:
+
+```ruby
+projection = Mxrb.open("Shop.mpr") do |project|
+  project.sql_to_oql(
+    'SELECT p."name" FROM "shop$product" p WHERE p."name" = :Name',
+    dialect: :postgresql
+  )
+end
+
+puts projection.oql if projection.supported?
+# SELECT p/Name FROM Shop.Product p WHERE p/Name = $Name
+```
+
+O comando unificado `query` converte nas duas direções; `--input -` lê de stdin
+e `--json` retorna o resultado tipado:
+
+```sh
+bundle exec mxrb query \
+  'SELECT p."name" FROM "shop$product" p WHERE p."name" = :Name' \
+  --from sql --to oql --project Shop.mpr --dialect postgresql
+bundle exec mxrb query 'SELECT p/Name FROM Shop.Product p' \
+  --from oql --to sql --dialect sql_server
+bundle exec mxrb query --input query.sql --from sql --dialect sql_server --json
+```
+
+O subconjunto inclui aliases, joins explícitos, fontes separadas por vírgula,
+`WHERE`, `GROUP BY`, `HAVING`, `UNION`, `ORDER BY`, `LIMIT`/`OFFSET`, funções
+OQL conhecidas e parâmetros nomeados (`:Name`, `@Name` ou `$Name`). Tabelas
+físicas `module$entity` viram `Module.Entity`; sem `--project`, a capitalização
+é inferida e o resultado recebe confiança `inferred`.
+
+Escritas, múltiplas instruções, CTEs, subconsultas em `FROM`/`JOIN`, parâmetros
+posicionais, funções desconhecidas e extensões sem equivalente OQL seguro, como `ILIKE`,
+`DISTINCT ON`, `TOP`, `::` e concatenação `||`, retornam `supported? == false`
+com uma explicação em `warnings`.
+
 ## Análise dialect-aware
 
 `Oql::Analyzer` encontra padrões de custo e portabilidade na fonte original,