Bootstrap prompt: interview first, multi-app solutions, and honour the configured app host name

[ako]

Follow-up to #105 (merged): the four commits that landed after its merge point. Mostly the bootstrap prompt, plus one runtime fix that came out of reviewing it.

The bootstrap prompt asks what the app is (docs-site/src/tools/bootstrap-prompt.md)

It hardcoded App, so every repo bootstrapped from it got App.mpr regardless of what was being built — and that name is the .mpr file name, the Studio Pro app name, and the path baked into the SessionStart hook, so it is awkward to change afterwards.

A Step 0 now asks for the shape (one app or a solution), the name, what the app is for, what it keeps track of, who logs in, the theme and the Mendix version — one message, defaults offered, and the agent is told not to block twice. The answers become a brief written to README.md and committed, so a session resuming after an idle reap knows what it is building. A closing step has the agent propose the model as readable MDL and wait, instead of inventing one.

Two corrections found while rewriting, both verified rather than assumed:

• "Create the app at the repo root: mxcli new App" cannot work. mxcli new refuses a non-empty directory and .git alone trips it; with no --output-dir it creates ./App/, leaving every later -p App.mpr wrong by one directory. Confirmed by running it in an empty git repo. The prompt now creates in a subfolder and moves the contents up, which is what the SessionStart hook's relative path needs.
• The blank template's module is MyFirstModule, not the app name, so the closing step asks for a module name explicitly.

Multi-app solutions

The prompt assumed one app at the repo root — fine for the common case, wrong for a backend that owns the data plus a frontend that consumes it. Added as deltas rather than a second prompt: per-app subfolders, explicit ports for the second app (8180/8190/6643 — 8081/8091/6544 belong to mxcli test --local), and --hub-solution so previews group. Databases need no action, since the name derives from the .mpr file name.

Two things the agent could not have inferred:

• mxcli init dedupes the SessionStart hook on the command, not on the project, so a second app never gets its own entry — and Claude Code reads the root .claude/settings.json, not the per-app ones. The root file has to be written by hand, one line per app.
• CREATE ODATA CLIENT fetches $metadata at creation time and caches it, warning rather than failing when unreachable. So the producer must be published and running before the consumer is wired, and ServiceUrl belongs in a constant since it will not stay localhost.

Default Mendix version 11.6.3 → 11.13.0, with a note on what "newest supported" means. Confirmed mxbuild-11.13.0.tar.gz and mendix-11.13.0.tar.gz both serve 200 and 11.14.0 serves neither.

Each app gets its own host name

Separating a solution's apps by port alone does not separate their sessions: cookies key on host name and ignore the port, so localhost:8080 and localhost:8180 share one jar and a login to one can replace the other's XASSESSIONID.

Distinct hostnames fix it and need no mxcli change — worth stating explicitly, because the obvious alternative (one loopback IP per app on a shared port) is not possible: the runtime binds 127.0.0.1 and there is no listen-address flag. Verified against a booted app: a foreign Host header is served 200 via /etc/hosts, nip.io and localtest.me alike, and the client uses relative URLs. /etc/hosts is recommended over public wildcard DNS for locked-down containers, where localtest.me resolves to ::1.

run --local honours the configured Application root URL

The project's own configuration is where a custom host name belongs — versioned with the app, per configuration, no flag to repeat:

alter settings configuration 'Default'
  ApplicationRootUrl = 'http://backend.local:8080/';

run --local ignored it. The boot payload's ApplicationRootUrl came only from a --hub registration, and since update_configuration replaces rather than merges, nothing else could supply it. It is now read at boot and used when no hub URL was assigned (a hub assignment wins, being the URL actually serving the app).

Serving under a host name works without this; what it fixes is the absolute URLs Mendix generates — OIDC/SAML redirect URIs, deep links — which kept naming the listen address.

The trap: a blank Mendix app already ships ApplicationRootUrl = http://localhost:8080/, so "is set" does not mean "was chosen". Honouring every value would change behaviour for every existing project and, under --app-port, advertise a port the app is not serving on. Only a non-loopback host is passed through; a port disagreeing with --app-port warns.

Validation

• go build ./... and the affected cmd/mxcli/docker tests pass on the rebased base
• New unit tests: TestApplicationRootURLFrom (Default wins wherever it sits, case-insensitive, first-with-a-URL otherwise) and TestCustomHostRootURL (including the stock localhost:8080 value)
• End-to-end on Mendix 11.12.1: with backend.local configured, the boot prints the configuration it came from and the app answers 200 on both the host name and the listen address
• make check-skill-mdl passed on the docs changes before the rebase; a full make build sweep has not been re-run since and is left to CI

🤖 Generated with Claude Code

https://claude.ai/code/session_01JXnEgoc2NQP1Y2TWMCMXC4

---

Generated by Claude Code