@open-rap/compiler 0.0.0-stage → 0.1.0

package/docs/README.md

@@ -0,0 +1,148 @@
+# Open RAP Runtime
+
+**Develop, test and deploy your RAP business objects without an SAP system.**
+
+You write your RAP BO as in the ABAP Development Tools — tables, CDS views, UI annotations,
+behavior definition, behavior pool in ABAP, service — and Open RAP Runtime turns it into an
+application that runs anywhere: an OData V4 service, the RAP managed runtime with your ABAP code,
+a PostgreSQL database and a List Report / Object Page UI in OpenUI5. The same sources are then
+imported into SAP with abapGit.
+
+![Generated List Report](docs/images/list-report.png)
+
+## What it is for
+
+- **Learning and teaching RAP** without a license or a system: the complete cycle BDEF → behavior
+  pool → OData → Fiori, locally, in a few seconds.
+- **Prototyping** a BO and showing it to a customer or a business team before opening a system.
+- **Testing** the logic of a BO (determinations, validations, actions, authorizations) in CI.
+- **Shipping a small standalone application** (Docker, SAP BTP Cloud Foundry, an internal server)
+  when an SAP system is not justified.
+- **Opening the BO to AI agents**: the service becomes an MCP server whose tools all apply the
+  checks of the BO.
+
+Everything is open source under permissive licenses: no CAP, no SAPUI5, no proprietary SAP
+library ([LICENSES.md](LICENSES.md)).
+
+## Get started in two minutes
+
+**In VS Code**: install the `open-rap-runtime-vscode.vsix` extension (it contains everything), then
+run *RAP: New complete business object…* and *RAP: Start rapt dev* (which asks for the floorplan).
+The browser opens on the development launchpad.
+
+**On the command line** (Node.js 22): `npm install -g open-rap-runtime` (or `npx open-rap-runtime`),
+or from a clone `pnpm install && pnpm build`, then `node packages/compiler/dist/cli.js` instead of
+`rapt`:
+
+```sh
+rapt new my-project Travel --prefix ZRT    # a complete managed BO, with data
+rapt dev my-project                         # http://localhost:8080/ — rebuilt on each save
+```
+
+![Development launchpad](docs/images/dev-launchpad.png)
+
+## What you get
+
+| You write (abapGit format) | Open RAP Runtime produces |
+|---|---|
+| Tables (`define table`, as in ADT), CDS table entities | PostgreSQL tables, initial data |
+| CDS views, projections, CDS types (simple, enumerated), DCL | SQL views, OData V4 `$metadata`, per-user access controls |
+| Metadata extensions (`@UI`) | List Report, Worklist, Analytical List Page, Overview Page (Fiori filters, user views, value helps, charts) and Object Page |
+| Behavior definition | RAP managed runtime: draft, locks, ETags, numbering, authorizations, feature control, determinations, validations, actions |
+| Behavior pool (ABAP Cloud) | The same code, transpiled and run: EML, messages, ABAP SQL, released classes (JSON, HTTP, bgPF, e-mail…) |
+| Service definition | OData V4 service at the SAP paths, `$batch`, CSRF, OIDC |
+| `rapt/mcp.json` | MCP server for AI agents |
+| `launchpad.json` | OpenUI5 launchpad: spaces, pages, tiles by role, single sign-on; one per workspace, created and completed when each application is created |
+
+![Object Page in edit mode](docs/images/object-page.png)
+
+## Key features
+
+- **Write only ABAP**: `rapt new` (a complete BO), `rapt generate` (a table, a view from its
+  table, a projection, a BDEF with its compositions, a behavior pool…), `rapt abapgit` (the XML
+  files for the import into SAP).
+- **Development loop** `rapt dev`: embedded database, rebuild on each save, positioned
+  diagnostics (`file:line:column`), development launchpad with the built-in documentation.
+- **Modes**: `standard` (strictly as on SAP, activatable on SAP) or `enhanced` (extensions:
+  mandatory fields checked automatically, managed BO on a custom entity, CDS enumerated types
+  exposed as OData `EnumType`).
+- **Draft** (`with draft`, `with collaborative draft`): drafts, Edit / Activate / Discard,
+  exclusive lock, editing status, invited users, as in Fiori Elements.
+- **Table entities and CDS types**: a complete BO on a `define table entity`, simple and
+  enumerated types.
+- **Standard views** `I_Currency`, `I_UnitOfMeasure`, `I_Country`, `I_Language`, `I_Region`,
+  `I_CalendarDate`, `I_TimeZone`, `I_BusinessUserBasic`, `I_ExchangeRate` with their data, for
+  your value helps.
+- **Fiori UI**: List Report, Worklist, Analytical List Page (`$apply`), Overview Page, Form entry;
+  filters with conditions (`>100`, `1...5`, `*abc*`, `!(…)`) and the *Search and Select* /
+  *Define Conditions* dialog, views saved per user, table settings, value helps, actions,
+  editable compositions.
+- **CDS expressions**: calculated elements (`CASE`, `CAST`, arithmetic, SQL functions) computed
+  by the database view.
+- **Security**: OIDC (Keycloak, SAP Cloud Identity Services, Entra ID…), Web API bindings with
+  OAuth 2.0 (client credentials, PKCE), authorization objects and `AUTHORITY-CHECK`, DCL, roles.
+- **One launchpad per workspace**: each application is added to it when it is created; ship
+  either the launchpad with all its applications (`rapt launchpad`) or one application alone
+  (`rapt build`).
+- **Deployment**: Docker, `docker compose`, SAP BTP Cloud Foundry (`cf push`), any Node.js
+  server.
+- **VS Code extension**: object creation wizard as in ADT, *RAP Objects* view, floorplan choice,
+  every command of the CLI, diagnostics in the Problems tab, ABAP, CDS and BDEF highlighting;
+  `rapt` in the integrated terminals.
+- **AI coding agents**: `rapt agent`, an MCP server that checks the project, creates objects and
+  searches the documentation; registered by the extension for the agent mode of VS Code.
+
+![Filter dialog: Search and Select, Define Conditions](docs/images/filter-dialog.png)
+
+## Documentation
+
+| Document | Content |
+|---|---|
+| [Guide](docs/GUIDE.md) | Everything Open RAP Runtime does and how to use it (humans and AI agents) |
+| [Features](docs/FEATURES.md) | RAP coverage, feature by feature |
+| [Annotations](docs/ANNOTATIONS.md) | Each CDS annotation: what the `$metadata` and the UI do with it |
+| [Diagnostics](docs/DIAGNOSTICS.md) | The codes of `rapt check` |
+| [MCP server](docs/MCP.md) | The service for AI agents |
+| [Deployment](docs/DEPLOYMENT.md) | Docker, SAP BTP Cloud Foundry, HTTPS, publishing a version (npm, extension) |
+| [Utility classes](docs/UTILITIES.md), [Remote APIs](docs/REMOTE_APIS.md) | The behavior pool beyond RAP |
+| [Known gaps](KNOWN_GAPS.md), [Roadmap](docs/ROADMAP.md) | What is missing, what is coming |
+| [Decisions](docs/DECISIONS.md), [Plan](PLAN.md) | The technical choices and their reasons |
+
+The same documentation opens from the launchpad of `rapt dev` (*Documentation* tile), and on the
+project website.
+
+The project website (`site/`, published on GitHub Pages by the `site.yml` workflow) presents
+Open RAP Runtime, contains this documentation and serves the `.vsix` of the latest version.
+
+## Feedback
+
+Report a bug or request a feature with the
+[feedback form](https://clementringot.github.io/RAP-Transpiler/feedback.html) (it opens a
+pre-filled issue in the public
+[feedback repository](https://github.com/ClementRingot/open-rap-runtime-feedback)), or in VS Code
+with *RAP: Report a bug or request a feature…*.
+
+## Contributing
+
+```sh
+pnpm install
+pnpm build
+pnpm test                    # vitest: compiler, runtime, browser (Playwright if present)
+```
+
+```
+packages/model/      types of the IR (model.json), shared naming conventions
+packages/compiler/   rapt CLI, parsers (BDEF, CDS, SRVD, DCL), IR, generators
+packages/runtime/    runtime of the generated applications (OData V4, RAP managed, launchpad, MCP)
+packages/vscode/     VS Code extension (calls the rapt CLI)
+packages/cli/        npm package open-rap-runtime (the rapt command)
+fixtures/            reference BOs: travel (Travel / Booking), custom-entity, table-entity
+site/                project website
+```
+
+The rules for working on the repository (for humans and agents alike) are in
+[AGENTS.md](AGENTS.md).
+
+## License
+
+MIT ([LICENSE](LICENSE)); dependencies under permissive licenses ([LICENSES.md](LICENSES.md)).

package/docs/REMOTE_APIS.md

@@ -0,0 +1,121 @@
+# Consuming a remote API from the BO (SCM, SCM2, HTTP client)
+
+A behavior pool can call a remote API with the usual ABAP Cloud code: the HTTP client
+(`cl_web_http_client_manager`) for a REST API, the OData client proxy of a service consumption
+model for an OData V2 or V4 service. The generated application runs this code as is; only the
+destination is configured differently from SAP (decision D31).
+
+## 1. What to export with abapGit
+
+| On SAP | In the abapGit repository | What Open RAP Runtime does with it |
+|---|---|---|
+| Service consumption model 2 (OData V4) | the generated consumption model class (`INHERITING FROM /iwbep/cl_v4_abs_pm_model_prov`) | keeps its types (`tys_…`, `tyt_…`) and constants (`gcs_entity_set`…); the `define` method is removed |
+| Service consumption model (OData V2/V4, first generation) | the generated abstract entities and the service definition of the proxy | the abstract entities type the data; the service definition without a binding is not built (info SRVD007) |
+| REST API | nothing | |
+
+The `.srvc` file of the service consumption model itself is not needed: the proxy reads the
+`$metadata` of the remote service on its first call.
+
+## 2. The code of the behavior pool
+
+The same as on SAP, for example in an action:
+
+```abap
+METHOD importRemote.
+  DATA remote_travels TYPE zscm_rt_travel=>tyt_travel_type.
+  DATA travel_ids     TYPE RANGE OF zscm_rt_travel=>tys_travel_type-travel_id.
+
+  READ ENTITIES OF zrt_r_travel IN LOCAL MODE
+    ENTITY Travel FIELDS ( TravelID ) WITH CORRESPONDING #( keys )
+    RESULT DATA(travels).
+  travel_ids = VALUE #( FOR t IN travels ( sign = 'I' option = 'EQ' low = t-TravelID ) ).
+
+  TRY.
+      DATA(destination) = cl_http_destination_provider=>create_by_comm_arrangement(
+                            comm_scenario = 'ZRT_TRAVEL_REMOTE'
+                            service_id    = 'ZRT_TRAVEL_REMOTE_REST' ).
+      DATA(proxy) = /iwbep/cl_cp_factory_remote=>create_v4_remote_proxy(
+                      is_proxy_model_key       = VALUE #( repository_id       = 'DEFAULT'
+                                                          proxy_model_id      = 'ZSCM_RT_TRAVEL'
+                                                          proxy_model_version = '0001' )
+                      io_http_client           = cl_web_http_client_manager=>create_by_http_destination( destination )
+                      iv_relative_service_root = '/sap/opu/odata4/sap/zrt_ui_travel_o4/srvd/sap/zrt_ui_travel/0001/' ).
+
+      DATA(request) = proxy->create_resource_for_entity_set( zscm_rt_travel=>gcs_entity_set-travel )->create_request_for_read( ).
+      DATA(filter_factory) = request->create_filter_factory( ).
+      request->set_filter( filter_factory->create_by_range( iv_property_path = 'TRAVEL_ID' it_range = travel_ids ) ).
+      request->set_top( 50 ).
+      DATA(response) = request->execute( ).
+      response->get_business_data( IMPORTING et_business_data = remote_travels ).
+
+    CATCH /iwbep/cx_cp_remote INTO DATA(remote_error).
+      " remote_error->http_status_code, remote_error->get_text( )
+    CATCH /iwbep/cx_gateway cx_web_http_client_error cx_http_dest_provider_error INTO DATA(error).
+      " error->get_text( )
+  ENDTRY.
+ENDMETHOD.
+```
+
+The internal names of the class (`TRAVEL_ID`, `'TRAVEL'`) are matched with the names of the
+service (`TravelID`, `Travel`) ignoring case and `_`. Supported: list read (`create_by_range`,
+`and`/`or`/`not`, `set_select_properties`, `set_orderby`, `set_top`, `set_skip`,
+`request_count`, `request_no_business_data`), read by key (`navigate_with_key`), create, update
+(`PATCH` or `PUT`, `it_provided_property`, `set_if_match`), delete. The CSRF token and the
+session cookies of SAP Gateway are handled by the proxy.
+
+A REST API:
+
+```abap
+DATA(client) = cl_web_http_client_manager=>create_by_http_destination(
+                 cl_http_destination_provider=>create_by_cloud_destination( i_name       = 'RATINGS'
+                                                                            i_authn_mode = if_a4c_cp_service=>service_specific ) ).
+DATA(request) = client->get_http_request( ).
+request->set_uri_path( |/api/ratings/{ travel-TravelID }| ).
+request->set_header_field( i_name = 'Accept' i_value = 'application/json' ).
+DATA(response) = client->execute( if_web_http_client=>get ).
+DATA(status) = response->get_status( ).
+IF status-code = 200.
+  DATA(json) = response->get_text( ).
+ENDIF.
+```
+
+## 3. The destination
+
+On SAP, the URL and the credentials come from a communication arrangement or from the
+destination service of BTP. In the generated application, they are environment variables:
+
+| Variable | Content |
+|---|---|
+| `DESTINATION_<NAME>_URL` | base URL (mandatory) |
+| `DESTINATION_<NAME>_USER`, `DESTINATION_<NAME>_PASSWORD` | basic authentication |
+| `DESTINATION_<NAME>_TOKEN` | bearer token (`Authorization: Bearer`) |
+| `DESTINATION_<NAME>_HEADERS` | other headers, JSON object: `{"APIKey":"…"}` |
+
+`<NAME>` is the name of `create_by_cloud_destination` (`RATINGS`), or for
+`create_by_comm_arrangement`: `<SCENARIO>_<SERVICE_ID>`, otherwise `<SCENARIO>`
+(`ZRT_TRAVEL_REMOTE_ZRT_TRAVEL_REMOTE_REST`, then `ZRT_TRAVEL_REMOTE`), in upper case, the
+characters other than letters and digits replaced by `_`. `rapt build` lists the destinations
+written as literals in the `.env.example` and the README of the application. The credentials stay
+on the server: the ABAP only sees the URL.
+
+With docker compose, in the `app` service:
+
+```yaml
+    environment:
+      DESTINATION_ZRT_TRAVEL_REMOTE_URL: https://my-system.example.com
+      DESTINATION_ZRT_TRAVEL_REMOTE_USER: ${REMOTE_USER}
+      DESTINATION_ZRT_TRAVEL_REMOTE_PASSWORD: ${REMOTE_PASSWORD}
+```
+
+Behind an outgoing proxy: `HTTPS_PROXY=…` and `NODE_USE_ENV_PROXY=1`.
+
+## 4. Limits
+
+See [KNOWN_GAPS.md](../KNOWN_GAPS.md#remote-apis-d31): no `$batch`, `$expand`, deep insert,
+navigation by association nor actions of the remote service in the client proxy; value controls
+not filled; neither user propagation nor OAuth client credentials (a fixed token with `_TOKEN`);
+no communication targets, SOAP nor RFC. As on SAP, a remote call made during the interaction is
+not undone by a rollback of the LUW.
+
+Complete tested example: `packages/runtime/test/variants.ts` (`remoteVariant`) and
+`packages/runtime/test/rap-variant-remote.test.ts`.

package/docs/ROADMAP.md

@@ -0,0 +1,35 @@
+# Roadmap
+
+What is planned, with the design elements already known. The available features are in
+[FEATURES.md](FEATURES.md), the accepted gaps in [KNOWN_GAPS.md](../KNOWN_GAPS.md).
+
+## Draft: additions
+
+- Determinations and validations during editing (`Prepare`, `on modify` on the draft), state
+  messages (`%state_area`), actions of the application on a draft, `SiblingEntity`.
+- Real-time collaborative draft (WebSocket), field locks.
+
+## Floorplans: additions
+
+- Analytical List Page: visual filters, several charts, `@Aggregation`.
+- Overview Page described by annotations (`@UI.dataPoint`, `@UI.kpi`) rather than by
+  `rapt/config.json`.
+
+## CDS types and table entities: additions
+
+- CDS expressions: `CAST` to a CDS type or an enumerated type, `Type.#CONST` constants in the
+  views.
+- CDS expressions (continuation of D67): to-one association paths (`_Agency.Name`, left join in
+  the view), `BETWEEN`, `$session.user` and `$session.system_language` (PostgreSQL session
+  parameters set per request).
+
+## Other leads
+
+- Value helps: fixed values of the domains, several qualified value helps per element.
+- Standard views: texts in languages other than English, exchange rates from a configurable
+  source.
+- Variants shared between users, order of the columns.
+- Personalization of the launchpad by the user, notifications.
+- MCP: stdio transport, resources (the `$metadata`, the documentation), OAuth authorization of
+  the protocol.
+- Late numbering (`adjust_numbers`), RAP events (`RAISE ENTITY EVENT`), change documents.

package/docs/UTILITIES.md

@@ -0,0 +1,95 @@
+# ABAP Cloud utility classes in the behavior pool
+
+A behavior pool can use the released utility classes of ABAP Cloud with the usual code: JSON,
+encodings, numbering, dates, application log, hashing, random numbers, regular expressions,
+RTTS. Open RAP Runtime provides a "clean-room" implementation of them (written from the public
+signatures documented by SAP, no SAP code); the kernel of the application does what ABAP cannot
+do alone (read and write JSON, convert a code page, hash, compress, write to the database,
+describe a data object) (decision D40).
+
+Only the objects the project uses are given to the transpiler: a project that uses none of them
+does not change.
+
+## Available classes
+
+| Area | Classes | Methods and attributes |
+|---|---|---|
+| JSON | `/ui2/cl_json` | `serialize` (`compress`, `name`, `pretty_name`, `numc_as_string`, `ts_as_iso8601`, `name_mappings`, `format_output`, `hex_as_base64`), `deserialize` (`json`, `jsonx`, `pretty_name`, `name_mappings`), constants `pretty_mode` (`none`, `low_case`, `camel_case`, `extended`, `user`, `user_low_case`) and `c_bool` |
+| JSON (XCO) | `xco_cp_json` | `data->from_string`, `data->from_abap`, `->apply( … )`, `->to_string( )`, `->write_to( REF #( … ) )`, `data->builder( )` (`begin_object`, `end_object`, `begin_array`, `end_array`, `add_member`, `add_string`, `add_number`, `add_boolean`, `add_null`, `get_data`); transformations `camel_case_to_underscore`, `underscore_to_camel_case`, `pascal_case_to_underscore`, `underscore_to_pascal_case`, `boolean_to_abap_bool`, `abap_bool_to_boolean` |
+| Encodings | `cl_web_http_utility` | `encode_base64`, `decode_base64`, `encode_x_base64`, `decode_x_base64`, `encode_utf8`, `decode_utf8`, `escape_url`, `unescape_url`, `escape_html` |
+| | `cl_abap_conv_codepage` | `create_out( codepage )->convert( )`, `create_in( codepage )->convert( )`: UTF-8, UTF-16 (LE, BE), ISO-8859-1, windows-1252, US-ASCII |
+| | `cl_abap_gzip` | `compress_binary`, `decompress_binary`, `compress_text`, `decompress_text` |
+| | `xco_cp=>string`, `xco_cp=>xstring`, `xco_cp_character=>code_page`, `xco_cp_binary=>text_encoding->base64` | `as_xstring`, `as_string`, `value`, `split`, `join`, `append`, `prepend`, `to_upper_case`, `to_lower_case`, `starts_with`, `ends_with` |
+| Text | `cl_abap_char_utilities` | `newline`, `cr_lf`, `horizontal_tab`, `vertical_tab`, `form_feed`, `backspace`, `maxchar`, `charsize`, `byte_order_mark_utf8` |
+| | `cl_abap_string_utilities` | `del_trailing_blanks`, `c2str_preserving_blanks` |
+| Numbering | `cl_numberrange_runtime` | `number_get` (`quantity`, `subobject`, `toyear`; `number`, `returncode`, `returned_quantity`), `number_check`; exceptions `cx_number_ranges`, `cx_nr_object_not_found` |
+| Dates and timestamps | `cl_abap_tstmp` | `add`, `subtractsecs`, `subtract`, `compare`, `move`, `move_to_short`, `normalize`, `tstmp2utclong`, `utclong2tstmp`, `utclong2tstmp_short`, `systemtstmp_syst2utc`, `systemtstmp_utc2syst`, `td_add`, `td_subtract` |
+| | `cl_abap_utclong` | `diff`, `read` |
+| | `xco_cp=>sy`, `xco_cp_time` | `sy->user( )->name`, `sy->language( )->value`, `sy->date( )`, `sy->time( )`, `sy->moment( )`, `sy->unix_timestamp( )`; `xco_cp_time=>date( )`, `time( )`, `moment( )`; `->as( xco_cp_time=>format->abap / iso_8601_basic / iso_8601_extended )->value`, `->add( … )`, `->subtract( … )`, `year`, `month`, `day`, `hour`, `minute`, `second`; `xco_cp_time=>time_zone->user / utc` |
+| Application log | `cl_bali_log`, `cl_bali_header_setter`, `cl_bali_free_text_setter`, `cl_bali_message_setter`, `cl_bali_exception_setter`, `cl_bali_log_db`, `cl_bali_log_filter`, `if_bali_constants` | `create`, `create_with_header`, `set_header`, `add_item`, `get_all_items`, `get_handle`; `save_log`, `load_log`, `load_logs_via_filter`, `load_logs_w_items_via_filter`, `delete_log`; filter by object, subobject, external ID, user, time interval |
+| Hashing | `cl_abap_message_digest`, `cl_abap_hmac` | `calculate_hash_for_char`, `calculate_hash_for_raw`, `calculate_hmac_for_char`, `calculate_hmac_for_raw`, `string_to_xstring`: MD5, SHA1, SHA224, SHA256, SHA384, SHA512 |
+| Random numbers | `cl_abap_random`, `cl_abap_random_int`, `cl_abap_random_int8`, `cl_abap_random_float`, `cl_abap_random_decfloat34` | `cl_abap_random=>seed( )`, `create( seed min max )->get_next( )`; `int`, `intinrange`, `float` |
+| Regular expressions | `cl_abap_regex`, `cl_abap_matcher` | `create_pcre`, `create_posix`, `create_matcher`, `cl_abap_matcher=>create`, `create_pcre`, `matches`, `contains`, `find_next`, `find_all`, `match`, `get_match`, `get_offset`, `get_length`, `get_submatch`, `replace_all`, `replace_found`, `replace_next` |
+| RTTS | `cl_abap_typedescr`, `cl_abap_elemdescr`, `cl_abap_structdescr`, `cl_abap_tabledescr`, `cl_abap_refdescr`, `cl_abap_classdescr` | `describe_by_data`, `describe_by_data_ref`, `describe_by_object_ref`; `type_kind`, `kind`, `length`, `decimals`, `absolute_name`, `components`, `get_components( )`, `get_component_type( )`, `get_table_line_type( )`, constants `typekind_*` and `kind_*` |
+| Background processing | `cl_bgmc_process_factory`, `if_bgmc_op_single`, `if_bgmc_op_single_tx_uncontr`, `cl_abap_tx` | `get_default( )->create( )`, `set_name`, `set_operation`, `set_operation_tx_uncontrolled`, `save_for_execution( )` → monitor (`get_state( )`), `cl_abap_tx=>save( )` / `modify( )` |
+| E-mail | `cl_bcs_mail_message`, `cl_bcs_mail_textpart`, `cl_bcs_mail_binarypart` | `create_instance`, `set_sender`, `set_reply_to`, `add_recipient` (`to`, `cc`, `bcc`), `set_subject`, `set_main`, `add_attachment`, `send` (`et_status`, `ev_mail_status`), `send_async`; `create_text_plain`, `create_text_html` |
+| Types | `string_table`, `xstring_table`, `match_result(_tab)`, `submatch_result(_tab)`, `abap_compdescr_tab`, `abap_component_tab` | |
+
+## Numbering: `rapt/number-ranges.json`
+
+The number range objects and intervals are declared next to the sources, like the roles
+(`rapt/authorizations.json`), and are versioned with them:
+
+```json
+{
+  "ZRT_TRAVEL": {
+    "01": { "from": "1", "to": "99999999" }
+  }
+}
+```
+
+An interval can also have `subobject` and `toyear`. The numbers are drawn in the database of the
+application (table `rapt_number_range`); an interval missing from the file starts at 1. Changing
+the bounds keeps the current number. `number` is the last number of the drawn block, as on SAP:
+with `quantity`, the numbers go from `number - returned_quantity + 1` to `number`. `returncode`
+is `2` at the last number of the interval, `3` when the block was reduced; an exhausted interval
+raises `cx_number_ranges`.
+
+## Application log
+
+`cl_bali_log_db=>get_instance( )->save_log( )` writes the log into the database of the
+application (tables `rapt_application_log` and `rapt_application_log_item`), with the user and
+the time of the request. Log objects and subobjects do not have to be declared. The tables are
+only created when the code uses the log (or the numbering, for `rapt_number_range`).
+
+## Background processing (bgPF)
+
+`save_for_execution( )` records the process in the LUW of the request (table
+`rapt_background_process`, state `NEW`). Once the LUW is committed, the operation runs in a LUW
+of its own, with the same user, after the response to the request; a rolled-back LUW starts
+nothing.
+
+- **Controlled operation** (`if_bgmc_op_single`): the EML of the operation (without
+  `IN LOCAL MODE`) is saved at its end, as by the RAP framework; ABAP SQL only writes after
+  `cl_abap_tx=>save( )`.
+- **Uncontrolled operation** (`if_bgmc_op_single_tx_uncontr`): ABAP SQL writes whenever it wants;
+  `COMMIT ENTITIES` (with `RESPONSE OF`) saves the EML, `ROLLBACK ENTITIES` rolls back the LUW.
+- **State**: `SUCCESSFUL` or `ERRONEOUS` (with the text of the exception) in
+  `rapt_background_process`, read by `get_state( )` of the monitor.
+
+## E-mail
+
+`send( )` composes the mail (HTML or text, text and binary attachments, copies) and keeps it in
+the `rapt_mail` table of the LUW (state `WAITING`, `ev_mail_status` = `W`). Once the LUW is
+committed, it is sent through the SMTP server of `MAIL_SMTP_URL`
+(`smtp://user:password@server:587`, or `smtps://…:465`): state `SENT`, or `ERROR` with the
+reason. Without `MAIL_SMTP_URL`, the mail stays in `rapt_mail` (state `STORED`, complete MIME
+message in `raw_message`): handy with `rapt dev`. `MAIL_FROM` gives the sender when the code does
+not call `set_sender`. A rolled-back LUW sends nothing.
+
+## Differences with SAP
+
+See [KNOWN_GAPS.md](../KNOWN_GAPS.md), section "ABAP Cloud utilities". In short: the time zone of
+the user is UTC; numbering and log are written in the LUW of the request (rolled back with it);
+`describe_by_name`, `/ui2/cl_json=>generate` and associative arrays are not supported; regular
+expressions go through those of JavaScript.

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@open-rap/compiler",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Compiles SAP RAP sources (abapGit format) into a standalone Node.js OData V4 application.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://clementringot.github.io/RAP-Transpiler/",
+  "keywords": [
+    "sap",
+    "rap",
+    "abap",
+    "cds",
+    "odata",
+    "odata-v4",
+    "abapgit",
+    "compiler",
+    "cli"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "default": "./dist/cli.js"
+    }
+  },
+  "files": [
+    "dist",
+    "framework",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@abaplint/core": "2.120.98",
+    "@abaplint/transpiler": "2.14.24",
+    "chevrotain": "13.2.0",
+    "fast-xml-parser": "5.12.0",
+    "@open-rap/model": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/copy-docs.mjs"
+  }
 }