diff --git a/README.md b/README.md index bf8d88d..59ffc26 100644 --- a/README.md +++ b/README.md @@ -13,117 +13,45 @@ examples -> app_guide -> validate_view + screenshot_view -> deploy_app -> build_ The agent writes an ABAP class, validates the view **and looks at a picture of it** in seconds, deploys it, boots it in a real browser and looks at the -running app — then iterates. The two ways of seeing it cost three orders of -magnitude apart: `screenshot_view` renders the reconstructed view with no -backend at all, `run_app` boots the transpiled app and needs a build first. -Everything runs locally on infrastructure that already guards the abap2UI5 -ecosystem in CI: the abaplint transpiler + open-abap runtime, the framework's -express shim, the [samples-controls](https://github.com/abap2UI5/samples-controls) build -and boot gates, and the [abap2UI5-linter](https://github.com/abap2UI5/linter) -validation core. +running app — then iterates. Everything runs locally on infrastructure that +already guards the abap2UI5 ecosystem in CI: the abaplint transpiler + +open-abap runtime, the framework's express shim, the +[samples-controls](https://github.com/abap2UI5/samples-controls) build and boot +gates, and the [linter](https://github.com/abap2UI5/linter) validation core. -## Setup +## Documentation -The tools need different things, so you can stop at the level you need. Each -step adds the ones below it. +**→ [The MCP server, in full](https://abap2ui5.github.io/docs/advanced/mcp_server.html)** +— what MCP means here, the three setup levels and what each one buys, how to +register the server with your client, every tool with what the agent gets from +it, and the loop they are meant to be used in. -### Level 1 — validate and SEE views (~3 MB, a minute) +**→ [Building with AI](https://abap2ui5.github.io/docs/get_started/ai.html)** — +the whole AI setup in rising order of effort. This server is the top rung; the +cheaper ones matter first. -`validate_view` and `screenshot_view`, the two tools you reach for most: they -reconstruct the view your ABAP builds, check it against the UI5 API and -photograph it. No SAP system, no backend, no transpile — seconds per answer. +## Quick start -(`screenshot_view` additionally needs the linter's render runtime and a -browser: `npm i -D @abap2ui5/render-runtime && npx playwright install chromium` -in the linter checkout. `validate_view`'s property gate needs neither.) +Level 1 — `validate_view` and `screenshot_view`, the two tools most work +happens at (~3 MB, a minute): ```sh -git clone https://github.com/abap2UI5/linter # AI_VIEW_CHECK_HOME +git clone https://github.com/abap2UI5/linter # AI_VIEW_CHECK_HOME git clone https://github.com/abap2UI5/mcp-server cd linter && npm ci && cd ../mcp-server && npm ci ``` -The other tools answer with an actionable message naming what is missing -rather than failing — the server starts either way. - -### Level 2 — the catalogues and deploying (~110 MB) - -`examples`, `capabilities`, `app_guide`, `scaffold_app`, `generation_rules`, -`pitfalls`, `scope_of`, `deploy_app`. - -```sh -git clone https://github.com/abap2UI5/abap2UI5 # A2UI5_HOME -git clone https://github.com/abap2UI5/samples-controls # SAMPLES_CONTROLS_HOME -git clone https://github.com/abap2UI5/samples # SAMPLES_HOME -git clone https://github.com/abap2UI5/samples-stack # SAMPLES_STACK_HOME -cd abap2UI5 && npm ci && cd ../samples-controls && npm ci -``` - -`examples` needs only the clones — no install — and it is the cheapest useful -thing here: it answers *"has somebody already built a value help / a tree / -navigation between two apps"* out of **614 working apps in three repositories**, -and hands back a class to read rather than a snippet to trust. - -| repository | what it answers | -|---|---| -| `samples` (152) | the patterns, on a bare abap2UI5 install | -| `samples-controls` (430) | how a specific UI5 **control** is expressed — the demo kit, rebuilt | -| `samples-stack` (32) | the same, for apps that need OData, RAP, APC or the launchpad | - -Any one of the three is enough to start: a missing clone is reported in the -answer, not fatal. The neighbouring question, *"can abap2UI5 express this UI5 -control **at all**"*, is `capabilities`, out of samples-controls' -`CAPABILITIES.md`. Neither answers the other. - -### Level 3 — see the app (a browser, and time) - -`build_backend` + `run_app`: the screenshot loop. - -```sh -npx playwright install chromium -``` - -Then one `build_backend { mode: "full" }`, which transpiles the framework and -the corpus to Node. **Budget tens of minutes for that first build** — every -later one is incremental (~1–2 min). It is the slowest thing here by far, and -it is what buys an agent the ability to look at what it built. - -> **If you set this up earlier:** the corpus repository was `ai-demokit`, then -> `abap2UI5-api`, and is `samples-controls` today. Nothing needs changing — an -> existing checkout is still found under any of the three directory names, and -> `AI_DEMOKIT_HOME` is still read alongside `SAMPLES_CONTROLS_HOME`. - -### Register it with your client - -**Claude Code:** +Register it with Claude Code: ```sh claude mcp add abap2ui5 -- node /path/to/mcp-server/server.mjs ``` -**Cursor** (`.cursor/mcp.json`), **VS Code** (`.vscode/mcp.json`), **Claude -Desktop** (`claude_desktop_config.json`) and anything else that reads the -standard stdio shape: - -```json -{ - "mcpServers": { - "abap2ui5": { - "command": "node", - "args": ["/path/to/mcp-server/server.mjs"], - "env": { - "AI_VIEW_CHECK_HOME": "/path/to/linter", - "A2UI5_HOME": "/path/to/abap2UI5", - "SAMPLES_CONTROLS_HOME": "/path/to/samples-controls" - } - } - } -} -``` - -The three `env` entries are only needed if the checkouts are not siblings of -`mcp-server`; drop the ones you stopped short of. VS Code wants the same object -under a top-level `"servers"` key rather than `"mcpServers"`. +Cursor, VS Code and Claude Desktop take the standard stdio shape — the +[documentation](https://abap2ui5.github.io/docs/advanced/mcp_server.html#registering-it-with-your-client) +has the JSON, and the two further levels (the sample catalogues and deploying, +then the headless build-and-boot loop). A tool whose prerequisites are missing +answers with a message naming what it needs; the server starts either way. The [abap2UI5 VS Code extension](https://github.com/abap2UI5/vscode-extension) registers this server for you, and adds a second one of its own for the tools @@ -133,66 +61,58 @@ that need a real SAP system. | Tool | What it does | |---|---| -| `capabilities` | Query the verified capability map (samples-controls CAPABILITIES.md, parsed live — no drift). Ask before assuming a UI5 feature is impossible: `{ query: "tree binding" }`, `{ status: "not-expressible" }` | -| `app_guide` | **How to build an app**, live from the framework checkout (abap2UI5 `docs/agents/building-apps.md`): app class template, lifecycle, the view-builder chain, binding, events, popups, navigation, portability. Whole guide by default; `{ section: "5" }` or `{ query: "popup" }` narrows it | -| `scaffold_app` | **The files a new project starts from**, live from abap2UI5/app-template: both gate configs with the framework pinned, the CI workflow, the abapGit metadata, an `AGENTS.md` briefing and a working app class with its sidecar. `{ class: "zcl_my_app" }` renames it throughout — the ABAP, the sidecar's `CLSNAME` and the file names, which is the part that decides whether the object activates. Returns files to write; writes nothing itself | -| `generation_rules` | The rulebook for **porting a UI5 demo-kit sample** into the samples-controls corpus. A different job from `app_guide` — it assumes an input sample and the corpus' naming | -| `pitfalls` | The catalogues of defects **a green CI does not catch**, parsed live from the abap2UI5 checkout: `{ area: "abap" }` (abapGit round trip and import, activation, extended check, downport/transpiler, runtime) and `{ area: "view" }` (names the 1.71 floor does not have, layout that only works on a newer release, views that fail to *load*). Every entry is a defect that actually shipped, with its evidence. `validate_view` decides what a rule can decide — this is the rest | -| `scope_of` | In/out-of-scope verdict for UI5 controls (since <= 1.71, not deprecated) | -| `validate_view` | **Seconds, not minutes**: static property gate + headless render via abap2UI5-linter, from ABAP source or raw XML — run this after writing, before deploying. Findings come with a severity, a message and the line/column in the source you passed in, plus what each rule that fired MEANS (`explain: true` for the full paragraph) — no web search to interpret a finding. Judged by your project's own `abap2ui5lint.jsonc`: pass `{ project_dir: "/path/to/your/repo" }`, or let it take the directory the server runs in | -| `deploy_app` | Write `.clas.abap` + abapGit sidecar into the gitignored sandbox `src/zz_dev/` (in the samples-controls checkout), then abaplint it. Any customer-namespace class name — `zcl_my_app` as much as `z2ui5_cl_my_app` | -| `build_backend` | Rebuild the transpiled Node backend. `mode: auto` is **incremental** after the first full build (~1-2 min per iteration); `mode: full` runs the complete e2e-build | -| `screenshot_view` | **See the view in seconds**, from source, with no build and no backend: reconstructed, rendered against the local OpenUI5 runtime and returned as an image. Several viewports in one session (`{ sizes: ["390x844", "1280x900"] }`), any theme, and `model` for preview data. What it cannot show is anything that only exists at runtime — that is `run_app` | -| `run_app` | Boot any app class headless (`?app_start=`), return boot status, real page errors (benign UI5 noise filtered) and a full-page **screenshot as an image**. The RUNNING app, so it needs a `build_backend` first | +| `capabilities` | Whether abap2UI5 can express a UI5 feature at all, from the verified capability map | +| `app_guide` | How to build an app, live from the framework checkout | +| `scaffold_app` | The files a new project starts from, live from app-template; `{ class: … }` renames throughout, sidecar `CLSNAME` included | +| `examples` | Search the three sample catalogues — answers with a class to read, never a snippet to trust | +| `generation_rules` | The rulebook for porting a UI5 demo-kit sample into samples-controls | +| `pitfalls` | The defects a green run does not catch: `{ area: "abap" }` and `{ area: "view" }` | +| `scope_of` | In/out-of-scope verdict for a UI5 control | +| `validate_view` | The linter's gates in seconds, judged by your project's own `abap2ui5lint.jsonc` | +| `screenshot_view` | See the view in seconds — no build, no backend | +| `deploy_app` | Write the class + abapGit sidecar into the gitignored sandbox, then abaplint it | +| `build_backend` | Rebuild the transpiled Node backend; incremental after the first full build | +| `run_app` | Boot an app headless: status, real page errors, and a **screenshot** | | `backend` | `status` / `start` / `stop` / `restart` of the local express backend | -| `remove_app` | Delete a dev app from the sandbox (or list the deployed ones) | - -`run_app` works for new dev apps and equally for the existing samples-controls -ports and `z2ui5_cl_smpc_app_overview` — useful as a reference: "run the closest -existing port, look at it, then build mine". - -## The intended agent loop - -1. `capabilities { query: ... }` — check the feature is expressible (and how) - before writing a line of ABAP. -2. `app_guide` — once per session, before writing any ABAP. (`generation_rules` - instead, if the job is porting a named demo-kit sample.) -3. `scaffold_app` — when the user wants a project of their own, not a class to - paste into one that exists. -4. Write the class, then `validate_view` **and** `screenshot_view` — the - findings and the picture, both in seconds and neither needing a build. Most - iterations should end here. -5. `deploy_app` — abaplint against the full framework context. -6. `build_backend` — incremental after the first full build. -7. `run_app` — read the errors, **look at the screenshot**. Edit, validate, - deploy, build, run again. -8. `pitfalls` before you call it done — the defects no gate here can see: what - the class does on a *real* system (abapGit import, activation, the extended - check) and what the view does on the *oldest* one. A green loop is not the - same as a shipped app. +| `remove_app` | Delete a dev app from the sandbox, or list the deployed ones | + +`screenshot_view` and `run_app` answer the same question at three orders of +magnitude apart: the first photographs the reconstructed **view** with no +backend, the second the **running app** after a build. Most iterations should +end at the first. ## Notes -- **Dev sandbox:** deployed apps land in the samples-controls checkout's gitignored - `src/zz_dev/` — nothing an agent deploys can leak into a commit. Promote a - finished app by moving it into a real package deliberately. +- **Dev sandbox:** deployed apps land in the samples-controls checkout's + gitignored `src/zz_dev/` — nothing an agent deploys can leak into a commit. - **Port:** the backend listens on 3000 (`A2UI5_MCP_PORT` overrides). - **Timeouts:** every spawned child is killed (whole process tree) when it exceeds its limit — lint/scope 5 min, build 30 min by default; `A2UI5_MCP_LINT_TIMEOUT_MS`, `A2UI5_MCP_SCOPE_TIMEOUT_MS` and `A2UI5_MCP_BUILD_TIMEOUT_MS` override (values in ms). -- **UI5 sources:** modules are served from the samples-controls checkout's - `@openui5` packages, so booting needs no network. The built theme CSS is - not in those packages — with network access it loads from the CDN (styled - screenshots); without, apps render unstyled but structurally complete. - `A2UI5_MCP_OFFLINE=1` forces the hermetic behaviour. -- **Chromium:** uses the Playwright-managed browser; if absent, falls back to - a system chromium (`A2UI5_MCP_CHROMIUM` overrides the executable path). -- **Real system deployment** stays what it is today: abapGit. This server is - the inner dev loop; the real-system half already exists in the +- **UI5 sources** are served from the samples-controls checkout's `@openui5` + packages, so booting needs no network. The built theme CSS is not in those + packages — with network access it loads from the CDN (styled screenshots); + without, apps render unstyled but structurally complete. `A2UI5_MCP_OFFLINE=1` + forces the hermetic behaviour. +- **Chromium:** uses the Playwright-managed browser; if absent, falls back to a + system chromium (`A2UI5_MCP_CHROMIUM` overrides the executable path). +- **If you set this up earlier:** the corpus repository was `ai-demokit`, then + `abap2UI5-api`, and is `samples-controls` today. Nothing needs changing — an + existing checkout is still found under any of the three directory names, and + `AI_DEMOKIT_HOME` is still read alongside `SAMPLES_CONTROLS_HOME`. +- **Real-system deployment** stays what it is today: abapGit. This server is + the inner dev loop; the real-system half lives in the [VS Code extension](https://github.com/abap2UI5/vscode-extension), whose own - MCP server exposes it as `run_app_on_system` (launch URL + auth proxy). Both - servers are registered in the same editor window, which is why that tool is - not called `run_app`: this one builds and boots the transpiled sandbox, that - one runs a class on a system, and an agent has to be able to tell them - apart. + MCP server exposes it as `run_app_on_system`. Both servers are registered in + the same editor window, which is why that tool is not called `run_app`. + +## Working on this repository + +```sh +npm ci +npm test +``` + +`AGENTS.md` carries the conventions, `CONTRIBUTING.md` and `RELEASING.md` the +rest of the workflow.