chore: process feedback comments

Author: leonardomendix

.claude/commands/mendix/e2e-spec.md

@@ -6,15 +6,16 @@ You are helping the developer write or improve Playwright e2e specs for a Mendix
 
 - Specs live at: `packages/pluggableWidgets/<widget>/e2e/*.spec.js`
 - Playwright strict mode is ON
-- Full rules: `docs/requirements/e2e-test-guidelines.md`
+
+> `<widget>` throughout this document is the package folder name, e.g. `badge-web`, `datagrid-web`.
 
 ## Discovering selectors and navigation from the test project
 
 Before writing selectors, look up the actual widget names and menu labels in the `.mpr`:
 
 ```bash
 # Full overview: modules, pages, entities, navigation menu labels
-bash automation/mxcli/mx-testproject.sh inspect <widget>
+bash automation/mxcli/mx-testproject.sh inspect badge-web   # replace with actual widget name
 
 # Widget structure of a specific page (reveals .mx-name-* values)
 bash automation/mxcli/mx-testproject.sh exec <widget> "DESCRIBE PAGE <Module>.<PageName>"
@@ -23,7 +24,7 @@ bash automation/mxcli/mx-testproject.sh exec <widget> "DESCRIBE PAGE <Module>.<P
 bash automation/mxcli/mx-testproject.sh list-pages <widget>
 
 # Search for a widget name across all project strings
-bash automation/mxcli/mx-testproject.sh search <widget> "<keyword>"
+bash automation/mxcli/mx-testproject.sh search <widget> 'keyword'
 ```
 
 The `inspect` output includes `DESCRIBE NAVIGATION Responsive` at the end — use those exact strings in `page.getByRole("menuitem", { name: "..." })`.
@@ -41,17 +42,19 @@ Standard naming convention per widget:
 
 ```bash
 # Full CI run (Docker):
-pnpm --filter @mendix/<widget> run e2e
+pnpm --filter @mendix/badge-web run e2e   # replace with actual widget name
 
-# Skip re-downloading the test project:
+# Skip re-downloading the test project (useful when iterating locally):
 pnpm --filter @mendix/<widget> run e2e --no-setup-project
 
-# Skip re-downloading and rebuilding:
+# Skip re-downloading and rebuilding (fastest iteration; requires local test project files):
 pnpm --filter @mendix/<widget> run e2e --no-setup-project --no-update-project
 ```
 
 ⚠️ Pass flags directly — do NOT use `pnpm run e2e -- --no-setup-project`. The `--` separator causes yargs-parser to ignore the flags.
 
+> Use `--no-setup-project --no-update-project` when you have the test project files locally and want to commit them to the `testProjects` repository after confirming tests pass.
+
 ## Checklist
 
 - [ ] Import from `@mendix/run-e2e/fixtures` — NOT `@playwright/test`

.claude/commands/mendix/e2e-workflow.md

@@ -7,12 +7,34 @@ If no widget name is provided, ask the user which widget they are working on (e.
 ## Prerequisites
 
 - `automation/tools/mxcli` must exist. If missing, run: `bash automation/mxcli/setup.sh`
-- The `.mpr` test project must be **closed in Studio Pro** before any mxcli edits
+- The `.mpr` test project must be **closed in Studio Pro** before any mxcli edits. Check with:
+    ```bash
+    ls packages/pluggableWidgets/<widget>/tests/testProject/.mendix-cache/lock 2>/dev/null \
+      && echo "⚠️ Studio Pro lock file present — close the project first" \
+      || echo "OK — no lock file"
+    ```
 - Docker must be running for the full CI e2e run
 
 ---
 
-## Phase 1 — Inspect the test project
+## Phase 1 — Download and inspect the test project
+
+Download the test project (if not already present):
+
+```bash
+pnpm --filter @mendix/<widget> run e2edev --setup-project
+```
+
+If this fails with `404 Not Found` / `Cannot find test project in GitHub repository`, the branch does not exist yet in `mendix/testProjects`. In that case:
+
+1. Copy an existing chart/widget MPR as a base (e.g. from `column-chart-web/tests/testProject/`).
+2. Place it at `packages/pluggableWidgets/<widget>/tests/testProject/<WidgetName>.mpr`.
+3. Copy the `widgets/`, `deployment/`, `theme/`, and `themesource/` folders from the same source.
+4. Replace the source widget's `.mpk` in `widgets/` with the new widget's built `.mpk` (run `pnpm --filter @mendix/<widget> run release` first).
+5. Adapt the domain model and microflows via mxcli (see `mendix:edit-test-project`).
+6. After Studio Pro has opened the MPR and registered the new widget type, push a new branch `<widget>` to `mendix/testProjects` so CI can download it.
+
+Then inspect:
 
 ```bash
 bash automation/mxcli/mx-testproject.sh inspect <widget>
@@ -24,6 +46,8 @@ This shows modules, pages, entities, and navigation menu labels in one call. For
 bash automation/mxcli/mx-testproject.sh exec <widget> "DESCRIBE PAGE <Module>.<PageName>"
 ```
 
+> **Note**: `DESCRIBE PAGE` may show an empty body for pages that only contain pluggable widgets. Use `automation/tools/mxcli bson dump -p <MPR> --type page --object <Module>.<Page>` and grep for widget names to verify content. See `mendix:edit-test-project` for details.
+
 **Output**: map of modules, pages, navigation labels, and `.mx-name-*` widget names.
 
 ---

.claude/commands/mendix/edit-test-project.md

@@ -22,7 +22,13 @@ Ask the user (or infer from context): which widget, and what scenario requires a
 ls packages/pluggableWidgets/<widget>/tests/testProject/*.mpr | grep -v backup
 ```
 
-Remind the user to close the project in Studio Pro before continuing.
+Verify Studio Pro is **not** holding the project open before any mxcli writes:
+
+```bash
+ls packages/pluggableWidgets/<widget>/tests/testProject/.mendix-cache/lock 2>/dev/null \
+  && echo "⚠️ Studio Pro lock file present — close the project first" \
+  || echo "OK — no lock file"
+```
 
 ## Step 3 — Inspect current state
 
@@ -33,12 +39,17 @@ bash automation/mxcli/mx-testproject.sh inspect <widget>
 # Targeted queries:
 automation/tools/mxcli -p <MPR_PATH> -c "SHOW PAGES IN <Module>"
 automation/tools/mxcli -p <MPR_PATH> -c "SHOW ENTITIES IN <Module>"
-automation/tools/mxcli -p <MPR_PATH> -c "SHOW ROLES IN <Module>"
-automation/tools/mxcli -p <MPR_PATH> -c "SHOW NANOFLOWS IN <Module>"
+automation/tools/mxcli -p <MPR_PATH> -c "SHOW MICROFLOWS IN <Module>"
 automation/tools/mxcli -p <MPR_PATH> -c "DESCRIBE PAGE <Module>.<PageName>"
-bash automation/mxcli/mx-testproject.sh search <widget> "<keyword>"
+bash automation/mxcli/mx-testproject.sh search <widget> 'keyword'
 ```
 
+> **`DESCRIBE PAGE` caveat**: pages containing only pluggable widgets (no built-in widgets like `DATAVIEW`, `LAYOUTGRID`, etc.) may render as an empty body even when widget content exists in the MPR. Use `automation/tools/mxcli bson dump -p <MPR> --type page --object <Module>.<Page>` and grep for widget names to verify content was written.
+
+> **`SEARCH` quoting**: use single-quoted strings — `SEARCH 'keyword'`, not `SEARCH "keyword"`. Double quotes cause a parse error.
+
+> **`SHOW ROLES IN <Module>`** — this MDL statement does not exist. Use `SHOW MODULES` output to see module source; roles are returned inline. To query roles programmatically use the catalog: `SELECT Name FROM CATALOG.USER_ROLES`.
+
 Run a baseline lint before editing:
 
 ```bash
@@ -93,13 +104,18 @@ test.beforeEach(async ({ page }) => {
 });
 ```
 
-For **brand-new empty pages** created by mxcli, direct URL works:
+For **brand-new empty pages** created by mxcli, the URL is auto-generated from the page name. Discover it with:
 
-```js
-await page.goto("/p/my-new-page");
+```bash
+automation/tools/mxcli -p <MPR_PATH> -c "DESCRIBE PAGE <Module>.<PageName>"
+# Look for the `url:` field in the output, e.g. url: 'my-page-name'
 ```
 
-After edits: Studio Pro shows "Project was modified externally" — click **Reload**.
+Then navigate directly in the spec:
+
+```js
+await page.goto("/p/my-page-name");
+```
 
 ## Step 5 — Rebuild and validate
 
@@ -114,11 +130,11 @@ Continue with `mendix:e2e-workflow` from Phase 4 (build → run → validate).
 | List modules               | `SHOW MODULES`                                                                |
 | List pages                 | `SHOW PAGES IN Module`                                                        |
 | List entities              | `SHOW ENTITIES IN Module`                                                     |
-| List roles                 | `SHOW ROLES IN Module`                                                        |
+| List microflows            | `SHOW MICROFLOWS IN Module`                                                   |
 | List nanoflows             | `SHOW NANOFLOWS IN Module`                                                    |
 | Describe page widgets      | `DESCRIBE PAGE Module.PageName`                                               |
 | Describe navigation menu   | `DESCRIBE NAVIGATION Responsive`                                              |
-| Search project strings     | `SEARCH "keyword"`                                                            |
+| Search project strings     | `SEARCH 'keyword'`                                                            |
 | Show callers of microflow  | `SHOW CALLERS OF Module.MicroflowName`                                        |
 | Show callers (transitive)  | `SHOW CALLERS OF Module.MicroflowName TRANSITIVE`                             |
 | Show references to element | `SHOW REFERENCES TO Module.ElementName`                                       |
@@ -134,10 +150,40 @@ Continue with `mendix:e2e-workflow` from Phase 4 (build → run → validate).
 | Validate MDL syntax + refs | `mxcli check changes.mdl -p app.mpr --references`                             |
 | Preview changes as diff    | `mxcli diff -p app.mpr changes.mdl`                                           |
 
+## Pluggable widget limitations
+
+mxcli can only create pluggable widget instances (`PLUGGABLEWIDGET '...' name (...)`) when the MPR **already contains an existing instance** of that widget type (Studio Pro registers the BSON template the first time the widget is imported). If no instance exists yet, mxcli fails with `template not found: <widgetname>`.
+
+**Workaround for a brand-new widget in a new test project:**
+
+1. Create the page with **named containers** and placeholder `DYNAMICTEXT` widgets (these are built-in and always work).
+2. Open the `.mpr` in Studio Pro — it will register the widget type from the `.mpk` in `tests/testProject/widgets/`.
+3. Inside each container, replace the placeholder with the actual pluggable widget instance.
+4. After Studio Pro saves, run `automation/tools/mxcli widget init -p <MPR>` to cache the widget definition.
+5. Future `PLUGGABLEWIDGET` statements for that widget will then work via mxcli.
+
+**Widget management commands:**
+
+```bash
+# Register widget definitions from all .mpk files in the project's widgets/ dir
+automation/tools/mxcli widget init -p <MPR_PATH>
+
+# Extract a .def.json skeleton from a specific .mpk (does not bootstrap the BSON template)
+automation/tools/mxcli widget extract --mpk <path>.mpk
+
+# List all registered widget definitions and their MDL keywords
+automation/tools/mxcli widget list -p <MPR_PATH>
+
+# Generate MDL syntax docs for a specific widget
+automation/tools/mxcli widget docs -p <MPR_PATH> <mdl-name>
+```
+
+The `widget list` output shows the MDL keyword (e.g. `bubblechart`) needed in `PLUGGABLEWIDGET` blocks. The keyword lookup is case-insensitive but the widget ID string is exact.
+
 ## Warnings
 
-- `CREATE OR MODIFY PAGE ... {}` wipes all widget content — never use on existing pages
-- Do NOT run mxcli while Studio Pro has the project open
+- Do NOT run mxcli while Studio Pro has the project open — check for the lock file (Step 2)
 - New pages need `GRANT VIEW ON PAGE` — missing it causes mxbuild exit code 3
 - `automation/tools/mxcli` is gitignored — run `bash automation/mxcli/setup.sh` on first checkout
+- `PLUGGABLEWIDGET` requires an existing instance in the MPR — use named containers as placeholders for brand-new widgets and configure them in Studio Pro first
 - Test project changes may require updating the `testProjects` repo branch for CI — flag this to the user

.claude/settings.json

@@ -10,8 +10,13 @@
             "mcp__plugin_playwright_playwright__browser_type",
             "mcp__plugin_playwright_playwright__browser_fill_form",
             "mcp__plugin_playwright_playwright__browser_press_key",
-            "mcp__plugin_playwright_playwright__browser_evaluate",
-            "Bash(bash automation/mxcli/mx-testproject.sh*)",
+            "Bash(bash automation/mxcli/mx-testproject.sh inspect *)",
+            "Bash(bash automation/mxcli/mx-testproject.sh list-pages *)",
+            "Bash(bash automation/mxcli/mx-testproject.sh search *)",
+            "Bash(bash automation/mxcli/mx-testproject.sh lint *)",
+            "Bash(bash automation/mxcli/mx-testproject.sh report *)",
+            "Bash(bash automation/mxcli/mx-testproject.sh callers *)",
+            "Bash(bash automation/mxcli/mx-testproject.sh refs *)",
             "Bash(bash automation/mxcli/setup.sh*)",
             "Bash(automation/tools/mxcli -p * -c \"SHOW*\")",
             "Bash(automation/tools/mxcli -p * -c \"DESCRIBE*\")",

automation/mxcli/mx-testproject.sh

@@ -84,7 +84,10 @@ case "$SUBCOMMAND" in
             | grep '^|' | grep -v '| Module ' | grep -v '^|---' \
             | grep -v '| System ' | grep -v '| Atlas_' \
             | awk -F'|' 'NR==1{gsub(/ /,"",$2); print $2}' || true)"
-        if [[ -n "$MODULE" ]]; then
+        if [[ -z "$MODULE" ]]; then
+            echo "Warning: could not auto-detect a non-System/non-Atlas module." >&2
+            echo "Run: bash automation/mxcli/mx-testproject.sh exec ${WIDGET} \"SHOW MODULES\"" >&2
+        else
             echo "=== Pages in ${MODULE} ==="
             run_mdl "SHOW PAGES IN ${MODULE}"
             echo ""
@@ -112,6 +115,7 @@ case "$SUBCOMMAND" in
             echo "Usage: exec <widget> \"<MDL statement>\"" >&2
             exit 1
         fi
+        echo "⚠️  Applying MDL directly — no diff preview. Use 'diff' subcommand first for mutating statements." >&2
         run_mdl "$MDL"
         ;;
     search)