@team-codeme/crud-forge 0.0.0-stage → 1.0.1

package/.cursor/agents/generator-engineer.md

@@ -0,0 +1,31 @@
+---
+name: generator-engineer
+description: Generator configuration, validation, templates, and generated-app integration for CRUDForge. Use for auth/IAM config schema, CLI commands, auth-pack environment wiring, and template changes that must not leak secrets.
+model: inherit
+---
+
+# Generator engineer
+
+## Responsibilities
+
+- Extend `auth` / `iam` configuration in defaults, YAML, `init-config`, and loaders without competing keys.
+- Validate required settings with actionable errors.
+- Resolve secret references (`passwordEnv`, `adminUsernameEnv`, `adminPasswordEnv`) in CLI/server-side code only.
+- Wire generated Angular auth to `serverUrl` / realm / public `clientId`. Never emit provision passwords or confidential client secrets into Angular environments, templates, or fixtures.
+- Keep `generate` from mutating remote Keycloak. Provisioning is a separate explicit command.
+- Preserve mock IAM (`useMockAuth: true`) and existing entity templates.
+
+## Constraints
+
+- Source of truth: `src/templates`, `src/generator`, `src/config`, `src/commands`.
+- Do not hand-edit testing-area `crudforge-app`, or `test/output*`.
+- Do not JDL-model User or Role.
+- Do not scatter hardcoded Keycloak hostnames in reusable defaults.
+
+## Report
+
+- Files changed
+- Config contract actually implemented (field names)
+- Backward-compat notes
+- Validation cases added
+- Anything that still emits secrets into generated apps

package/.cursor/agents/keycloak-engineer.md

@@ -0,0 +1,33 @@
+---
+name: keycloak-engineer
+description: Keycloak discovery, client provisioning, initial users/roles, and authentication integration. Use when bootstrapping realms via the project admin service, not assumed native Admin REST.
+model: inherit
+---
+
+# Keycloak engineer
+
+## Responsibilities
+
+- Discover the **real** admin-service API from code, docs, OpenAPI, or live introspection. Do not invent endpoints or assume native Keycloak Admin REST.
+- Verify realm, client, and privilege of supplied credentials before mutating anything.
+- Provision only configured resources: application client, roles, initial users, role assignments.
+- Idempotent bootstrap: check-then-create, no duplicate resources, no password reset unless `resetExistingPasswords` is true.
+- Dry run with zero remote mutations.
+- Track created resource IDs in a local state file for optional cleanup of **those** resources only.
+- Preserve unrelated clients (especially existing realm clients), users, realm settings, and role assignments.
+- Default QA application client ID: `crudforge-client-QA`. If it already exists unmanaged, use it as-is — never mutate unmanaged clients. Only create when missing (stamp `crudforge.owned=true` on creates).
+
+## Constraints
+
+- Provision credentials and initial-user passwords stay in CLI/server-side process. Never log them, never write them into Angular, git, screenshots, or fixtures.
+- Browser clients must be public (no confidential secret in the SPA).
+- If credentials lack privileges, finish local + mock coverage and report the exact blocked live operation and minimum access needed. Never call mock coverage a live pass.
+- Limit changes to configured resources.
+
+## Report
+
+- Discovered API contract (endpoints actually used)
+- Auth method and whether `crud` is admin, realm user, or neither
+- Resources created or modified (ids, names)
+- Dry-run vs apply results
+- Blockers and least privilege required

package/.cursor/agents/qa-engineer.md

@@ -0,0 +1,32 @@
+---
+name: qa-engineer
+description: Generator tests, Playwright, live Keycloak integration tests, CI, and failure evidence for CRUDForge. Use after generator/provision changes; keep mock IAM deterministic.
+model: inherit
+---
+
+# QA engineer
+
+## Responsibilities
+
+- Keep `npm test`, `test:e2e`, and `test:e2e:iam` (mock) passing.
+- Add a separately enabled **live** Keycloak suite with `useMockAuth: false`. Do not change `e2e-prepare-iam.js` to force live auth.
+- Cover config validation, idempotent bootstrap, generated app build, seeded login, bad password, anonymous redirect, RBAC (UI **and** backend/API where the service supports it), logout, IAM flows against real Keycloak, and useful errors for missing/insufficient/unreachable services.
+- `test-run.sh` must work from any cwd, load gitignored env, refuse unsafe cleanup, stop on failure, distinguish mock vs live.
+- CI: PR runs generator + mock Playwright. Live Keycloak is manual/scheduled with protected secrets. Untrusted PRs must not get live secrets.
+- Record failures with evidence. Redact tokens and passwords. Disable traces/screenshots that would capture credentials when redaction cannot be guaranteed.
+- Isolated, attributable test users. Serialize tests that mutate shared remote state. No fixed sleeps as the primary wait.
+
+## Constraints
+
+- Do not delete tests, weaken assertions, or hide failures.
+- After three unsuccessful attempts at the same failure, stop and report diagnosis + blocker.
+- Never report a blocked live run as passed.
+- Edit generator sources, not the testing-area `crudforge-app` / `test/output*`, as source of truth.
+
+## Report
+
+- Commands run and exit codes
+- Mock vs live distinction
+- Pass/fail/blocked per case
+- Artifacts (paths only; no secrets)
+- Remaining gaps

package/.cursor/agents/security-reviewer.md

@@ -0,0 +1,30 @@
+---
+name: security-reviewer
+description: Independent review of secret handling, authorization, Keycloak client configuration, and provisioning safety. Use after implementation; do not implement features in this role.
+model: inherit
+---
+
+# Security reviewer
+
+## Responsibilities
+
+- Independent review of the **final** diff for this Keycloak bootstrap work.
+- Check: secrets never in Angular bundles, committed fixtures, logs, or Playwright artifacts.
+- Check: confidential client secrets not sent to the browser; password grant vs public client implications.
+- Check: provisioning cannot run as a side effect of `generate`.
+- Check: env-ref resolution cannot leak unused secrets; dry-run does not send passwords to the server if avoidable.
+- Check: state-file cleanup cannot delete unrelated Keycloak resources.
+- Check: test users are isolated; admin credentials are not hardcoded.
+- Check: CI does not expose live secrets to untrusted pull requests.
+
+## Constraints
+
+- Review only. Do not “fix” by weakening tests or deleting coverage.
+- Do not request or paste production secrets into the report.
+- Findings must be severity-tagged: blocker / high / medium / low, with file paths.
+
+## Report
+
+- Verdict: approve / request changes
+- Findings list with severity and path
+- Residual risk (password grant, admin-service trust, QA host exposure)

package/.cursor/mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@playwright/mcp@latest",
+        "--browser=chromium",
+        "--isolated"
+      ]
+    }
+  }
+}

package/.cursor/rules/crudforge-precautions.mdc

@@ -0,0 +1,16 @@
+---
+description: CRUDForge generator precautions the agent must follow on every task
+alwaysApply: true
+---
+
+# CRUDForge precautions
+
+- Edit generator sources (`src/templates/**/*.ejs`, `src/generator`, `src/config`, `src/commands`). Do not hand-edit `test/output*` or a generated app unless the user is debugging that output.
+- Treat `new` and `edit` as the same `formMode`. Sidebar mode must open the list drawer for both. Page mode may route to `new` / `:id/edit`. Never leave edit on a full page while new uses the sidebar.
+- Change Fuse button and accent colors only through root `fuseTheme` in `src/app/app.ts` (wired by `provideTheming`) or `fuse.theme` in `crudforge.config.yml`. Do not scatter hardcoded primary colors in entity templates.
+- Default list search is `ui.searchMode: field` (JHipster `field.contains`). Use `global` only when the backend accepts a `query` param (Elasticsearch-style). Do not assume Elasticsearch is present.
+- Respect `output.overwritePolicy`. Never strip custom `// cforge-` merge zones. Do not rewrite the Fuse starter pack except through generator patches.
+- Bind generated HTTP servers to `0.0.0.0:$PORT`. The filesystem is ephemeral — do not rely on local writes for persistence.
+- After generator or template changes, run `node test/verify.js`. For UI bugs, use Playwright: `npm run e2e:prepare`, then `npm run e2e:serve` or `npm run test:e2e`. Generated Fuse app lives under `$CRUDFORGE_TESTING_AREA/crudforge-app` (default `/Users/abdulla/Work/CRUD-FORDGE-SETUP/crud-fordge-testing-area/crudforge-app`) — do not treat that copy as source.
+- Keycloak auth/IAM is an overlay (`auth.provider: keycloak`, `iam.enabled`). Do not model User or Role as JDL entities. Leave `auth.provider: none` unless the app needs real identity.
+- Never commit secrets, credentials, or live `.env` files.

package/.cursor/rules/playwright-browser.mdc

@@ -0,0 +1,30 @@
+---
+description: How the agent uses Playwright to browser-test generated CRUDForge apps
+alwaysApply: true
+---
+
+# Playwright browser testing
+
+The agent has Playwright access in two ways:
+
+1. **Playwright MCP** (`playwright-*` tools) for interactive exploration after the user reloads MCP.
+2. **`npm run test:e2e`** for repeatable checks against a generated Fuse mock app.
+
+## Before clicking around
+
+- Prepare the app once: `npm run e2e:prepare` (generates `$CRUDFORGE_TESTING_AREA/crudforge-app`, default `/Users/abdulla/Work/CRUD-FORDGE-SETUP/crud-fordge-testing-area/crudforge-app`).
+- Serve it: `npm run e2e:serve` (http://127.0.0.1:4200, mock configuration).
+- Demo sign-in is prefilled. Click **Sign in**, then open `/admin/book` or `/admin/author`.
+
+## What to verify
+
+- New and Edit both honor `formMode`. Sidebar mode must open `mat-drawer` / `.cforge-form-drawer`. Edit must not land on `/:id/edit` as a full page while New stays in the drawer.
+- Search-by is visible when `searchMode` is `field`. A single box is enough when `searchMode` is `global`.
+- Fuse button/accent color comes from root `fuseTheme` in `app.ts`, not hardcoded entity styles.
+- Hunt regressions on list, card, filter, confirm dialogs, and save/cancel.
+
+## Rules
+
+- Edit generator templates in `src/`, then re-run `e2e:prepare` before retesting. Do not patch the testing-area app as the source of truth.
+- Prefer accessibility snapshots and role/text locators over brittle CSS.
+- After UI fixes, run `npm run test:e2e` and `node test/verify.js`.

package/.cursor/rules/readme-todo-sync.mdc

@@ -0,0 +1,13 @@
+---
+description: Keep README.md and Todo.md current after meaningful project updates
+alwaysApply: true
+---
+
+# README and Todo sync
+
+Whenever you complete a meaningful feature, fix, config change, QA addition, or CLI change in this repo:
+
+1. Update `README.md` with user-facing commands, options, config keys, and how-to notes that changed.
+2. Update `Todo.md`: check off finished backlog items, add new known gaps, and refresh the "Suggested next slice" if priorities shifted.
+
+Do this in the same turn as the implementation—do not wait to be asked. Keep both files accurate; do not invent completed work.

package/.env.qa.example

@@ -0,0 +1,19 @@
+# Copy to .env.qa (gitignored). Never commit real production passwords.
+#
+# Real Keycloak endpoints are hardcoded in test-run.sh + e2e/crudforge.iam-live.yml.
+# Operator / SPA login (adminUsernameEnv / adminPasswordEnv) = crud / crud.
+
+KEYCLOAK_ADMIN_USERNAME=crud
+KEYCLOAK_ADMIN_PASSWORD=crud
+
+# Seeded application users (CLI bootstrap / live Playwright ACL cases)
+CRUDFORGE_QA_ADMIN_PASSWORD=change-me-admin
+CRUDFORGE_QA_USER_PASSWORD=change-me-user
+
+# Live Playwright / test-run paths
+CRUDFORGE_TESTING_AREA=/Users/abdulla/Work/CRUD-FORDGE-SETUP/crud-fordge-testing-area
+CRUDFORGE_E2E_APP_NAME=crudforge-app
+CRUDFORGE_LIVE_OUTPUT_DIR=
+CRUDFORGE_LIVE_BASE_URL=http://127.0.0.1:4202
+CRUDFORGE_LIVE_ADMIN_USERNAME=crudforge-qa-admin
+CRUDFORGE_LIVE_USER_USERNAME=crudforge-qa-user

package/.github/workflows/qa-live.yml

@@ -0,0 +1,32 @@
+name: QA (live Keycloak)
+
+# Protected secrets only. Do not run on untrusted pull_request forks.
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 4 * * 1"
+
+jobs:
+  live:
+    runs-on: ubuntu-latest
+    timeout-minutes: 40
+    environment: keycloak-qa
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+      - run: npm ci
+      - run: npx playwright install --with-deps chromium
+      - name: Live Keycloak bootstrap + Playwright
+        env:
+          CRUDFORGE_KC_SERVER_URL: ${{ secrets.CRUDFORGE_KC_SERVER_URL }}
+          CRUDFORGE_KC_REALM: ${{ secrets.CRUDFORGE_KC_REALM }}
+          CRUDFORGE_KC_CLIENT_ID: ${{ secrets.CRUDFORGE_KC_CLIENT_ID }}
+          CRUDFORGE_KC_FORWARDED_PROTO: https
+          KEYCLOAK_ADMIN_USERNAME: ${{ secrets.KEYCLOAK_ADMIN_USERNAME }}
+          KEYCLOAK_ADMIN_PASSWORD: ${{ secrets.KEYCLOAK_ADMIN_PASSWORD }}
+          CRUDFORGE_QA_ADMIN_PASSWORD: ${{ secrets.CRUDFORGE_QA_ADMIN_PASSWORD }}
+          CRUDFORGE_QA_USER_PASSWORD: ${{ secrets.CRUDFORGE_QA_USER_PASSWORD }}
+        run: bash test-run.sh live

package/.github/workflows/qa.yml

@@ -0,0 +1,27 @@
+name: QA (mock)
+
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+
+jobs:
+  mock:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+      - run: npm ci
+      - run: npx playwright install --with-deps chromium
+      - name: Generator tests
+        run: npm test
+      - name: Mock Playwright (CRUD + IAM)
+        run: |
+          npm run e2e:prepare
+          npm run test:e2e
+          npm run e2e:prepare:iam
+          npm run test:e2e:iam

package/.vscode/settings.json

@@ -0,0 +1,32 @@
+{
+    "workbench.colorCustomizations": {
+        "activityBar.activeBackground": "#ab307e",
+        "activityBar.background": "#ab307e",
+        "activityBar.foreground": "#e7e7e7",
+        "activityBar.inactiveForeground": "#e7e7e799",
+        "activityBarBadge.background": "#25320e",
+        "activityBarBadge.foreground": "#e7e7e7",
+        "activityBarTop.activeBackground": "#ab307e",
+        "activityBarTop.background": "#ab307e",
+        "activityBarTop.foreground": "#e7e7e7",
+        "activityBarTop.inactiveForeground": "#e7e7e799",
+        "commandCenter.border": "#e7e7e799",
+        "commandCenter.foreground": "#e7e7e7",
+        "sash.hoverBorder": "#ab307e",
+        "statusBar.background": "#832561",
+        "statusBar.debuggingBackground": "#832561",
+        "statusBar.debuggingForeground": "#e7e7e7",
+        "statusBar.foreground": "#e7e7e7",
+        "statusBarItem.hoverBackground": "#ab307e",
+        "statusBarItem.remoteBackground": "#121907",
+        "statusBarItem.remoteForeground": "#e7e7e7",
+        "titleBar.activeBackground": "#832561",
+        "titleBar.activeForeground": "#e7e7e7",
+        "titleBar.inactiveBackground": "#83256199",
+        "titleBar.inactiveForeground": "#e7e7e799",
+        "activityBar.activeBorder": "#e7e7e7",
+        "activityBarTop.activeBorder": "#e7e7e7",
+        "statusBar.inactiveBackground": "#832561"
+    },
+    "peacock.color": "#832561"
+}

package/QA/IAM-PLAN.md

@@ -0,0 +1,25 @@
+# IAM pack QA plan
+
+**Target:** generated Fuse IAM mock app (`e2e/.iam-app`) at http://127.0.0.1:4201  
+**Build:** `npm run e2e:prepare:iam` then `npm run e2e:serve:iam`  
+**Sign-in:** `demo@crudforge.com` / `admin` (`auth.useMockAuth: true`)  
+**Pack under test:** Keycloak auth overlay + user-management IAM
+
+## Scope
+
+In scope: mock Keycloak sign-in, AuthGuard, Identity nav, users CRUD dialog, user detail, change password, roles, role-permission matrix, user-access matrix, user-permission matrix.
+
+Out of scope: live Keycloak, PMB-specific extras, existing Book/Author CRUD (covered by `QA/TESTCASES.md`).
+
+## Entry criteria
+
+- `e2e/.iam-app` generated from current `src/templates/angular/auth` and `iam`
+- App serves on port 4201 without compile errors
+- Playwright Chromium installed
+
+## Exit criteria
+
+- Every case in `IAM-TESTCASES.md` has Pass / Fail / Blocked
+- Failures logged in `IAM-RESULTS.md` with severity and repro
+- `npm run test:e2e:iam` matches the automated subset
+- Defects filed against `src/templates/**`, not `e2e/.iam-app`

package/QA/IAM-RESULTS.md

@@ -0,0 +1,39 @@
+# IAM pack QA results
+
+**Date:** 2026-09-05  
+**Target:** `e2e/.iam-app` at http://127.0.0.1:4201  
+**Suite:** `npx playwright test --config=playwright.iam.config.js`  
+**Generator check:** `node test/verify.js` passed
+
+## Summary
+
+All 13 automated IAM cases passed after applying the PMB user-management UI/UX concept to the generated pack (Fuse list shell, side drawer create/edit/view, master-detail roles, card-style matrices).
+
+| Result | Count |
+|---|---|
+| Pass | 13 |
+| Fail | 0 |
+| Blocked | 0 |
+
+## Cases
+
+| ID | Result | Notes |
+|---|---|---|
+| IAM-AUTH-01 | Pass | Mock admin reaches `/admin`. |
+| IAM-AUTH-02 | Pass | Bad password stays on sign-in. |
+| IAM-AUTH-03 | Pass | Anonymous `/admin/user-management` redirects to sign-in. |
+| IAM-NAV-01 | Pass | Sidebar group is User Management. Users, Roles, Role permissions visible. |
+| IAM-USER-01 | Pass | List heading and mock admin row. |
+| IAM-USER-02 | Pass | New opens the list drawer (`New User`), Save adds the row. |
+| IAM-USER-03 | Pass | View opens the profile drawer. |
+| IAM-USER-04 | Pass | Change password dialog closes after Save. |
+| IAM-ROLE-01 | Pass | `ROLE_ADMIN` in the left role list. |
+| IAM-ROLE-02 | Pass | Create Role panel creates and selects the role. |
+| IAM-PERM-01 | Pass | Role matrix shows ROLE_ADMIN and screen rows. |
+| IAM-ACCESS-01 | Pass | Created ROLE_READER can be toggled on the user access matrix. |
+| IAM-UPERM-01 | Pass | User screen toggle flips. |
+
+## Defects fixed during this pass
+
+1. **Role create UX** — inline Material form left Create disabled under Playwright `fill()`. Replaced with PMB-style Create Role panel and native fields.
+2. **Mock store reset** — full navigation wiped in-memory users/roles. Mock Keycloak state now persists in `sessionStorage` (`cforge-iam-mock`).

package/QA/IAM-TESTCASES.md

@@ -0,0 +1,36 @@
+# IAM pack test cases
+
+Automated cases are tagged `[auto]`.
+
+## Auth
+
+| ID | Title | Steps | Expected | Tag |
+|---|---|---|---|---|
+| IAM-AUTH-01 | Mock admin sign-in | Open `/auth/sign-in`. Use `demo@crudforge.com` / `admin`. | Lands on `/admin/welcome`. | [auto] |
+| IAM-AUTH-02 | Bad password | Sign in with a wrong password. | Stays on sign-in. Shows invalid credentials. | [auto] |
+| IAM-AUTH-03 | Auth guard | Open `/admin/user-management` signed out. | Redirects to `/auth/sign-in`. | [auto] |
+
+## Navigation
+
+| ID | Title | Steps | Expected | Tag |
+|---|---|---|---|---|
+| IAM-NAV-01 | User Management menu | Sign in as admin. | Sidebar group is User Management. Users, Roles, Role permissions appear. | [auto] |
+
+## Users
+
+| ID | Title | Steps | Expected | Tag |
+|---|---|---|---|---|
+| IAM-USER-01 | Users list | Open `/admin/user-management`. | Heading User Management. Mock `admin` row. | [auto] |
+| IAM-USER-02 | Create user | Click New. Fill username and save. | Dialog closes. New username is in the table. | [auto] |
+| IAM-USER-03 | View details | Click View on admin. | Drawer shows User Details. | [auto] |
+| IAM-USER-04 | Change password | On detail, change password and save. | Dialog closes without error. | [auto] |
+
+## Roles and matrices
+
+| ID | Title | Steps | Expected | Tag |
+|---|---|---|---|---|
+| IAM-ROLE-01 | Roles list | Open `/admin/user-management/roles`. | `ROLE_ADMIN` appears in the left list. | [auto] |
+| IAM-ROLE-02 | Create role | Click Create Role, enter a name, Create. | Role is selected in the master-detail pane. | [auto] |
+| IAM-PERM-01 | Role matrix | Open role-permissions. | ROLE_ADMIN column and screen rows render. | [auto] |
+| IAM-ACCESS-01 | Assign role | Create ROLE_READER. On admin access, toggle it on. | Switch stays checked. | [auto] |
+| IAM-UPERM-01 | User screens | On admin permissions, toggle a book screen. | Switch flips. | [auto] |

package/QA/IAM-TODO.md

@@ -0,0 +1,7 @@
+# IAM QA agent todo
+
+- [x] Confirm `e2e/.iam-app` exists and `npm run e2e:serve:iam` is healthy on :4201
+- [x] Run `npm run test:e2e:iam`
+- [x] Record results in `QA/IAM-RESULTS.md`
+- [x] File template defects against `src/templates/angular/auth` or `iam`
+- [x] Re-run prepare + tests after template fixes

package/QA/KEYCLOAK-BOOTSTRAP.md

@@ -0,0 +1,105 @@
+# Keycloak bootstrap and live QA
+
+CRUDForge can **configure** Keycloak for generated apps and **optionally provision** a client, realm roles, initial users, and role assignments. `generate` never mutates a remote realm.
+
+## Commands
+
+```bash
+# Mock (no Keycloak mutations)
+./test-run.sh mock
+npm test
+npm run e2e:prepare && npm run test:e2e
+npm run e2e:prepare:iam && npm run test:e2e:iam
+
+# Live (requires .env.qa)
+cp .env.qa.example .env.qa   # gitignored
+./test-run.sh live
+# or:
+node cli.js bootstrap --preferences e2e/crudforge.iam-live.yml --env-file .env.qa
+node cli.js bootstrap --preferences e2e/crudforge.iam-live.yml --env-file .env.qa   # idempotent
+npm run e2e:prepare:iam:live
+npm run e2e:serve:iam:live   # http://127.0.0.1:4202  (development config, not mock)
+npm run test:e2e:iam:live
+```
+
+`test-run.sh` resolves paths from its own location, so it can be invoked from any cwd.
+
+## Environment
+
+| Variable | Purpose |
+|---|---|
+| `CRUDFORGE_KC_SERVER_URL` | Keycloak base URL (e.g. `http://62.84.188.166:30080`) — not the admin console deep-link |
+| `CRUDFORGE_KC_REALM` | Realm name (`CRUD-FORDGE`) |
+| `CRUDFORGE_KC_CLIENT_ID` | Public SPA client (`crudforge-client-QA`) |
+| `CRUDFORGE_KC_ADMIN_SERVICE_URL` | Keycloak middleware / admin service (`http://62.84.188.166:31740/`) |
+| `CRUDFORGE_KC_FORWARDED_PROTO` | Sent as `X-Forwarded-Proto` when Keycloak requires HTTPS behind HTTP |
+| `KEYCLOAK_ADMIN_USERNAME` / `KEYCLOAK_ADMIN_PASSWORD` | CLI bootstrap operator (QA: `crud` / `crud`) |
+| `CRUDFORGE_QA_ADMIN_PASSWORD` / `CRUDFORGE_QA_USER_PASSWORD` | Seeded app users |
+
+Passwords stay in the CLI process. They are not written to Angular `environment.ts`.
+
+## Adapters
+
+- `auth.provision.adapter: admin-service` — documented `GET /api/v1/*` on the custom wrapper. **Create client/user/role is not in that contract.** Requires realm role `KEYCLOAK_ADMIN_ACCESS`.
+- `auth.provision.adapter: keycloak-admin-rest` — native Keycloak Admin REST on `auth.serverUrl`. Used for QA bootstrap against public SPA client `crudforge-client-QA` (uses existing client as-is when unmanaged).
+
+Existing unmanaged clients are **not** modified. Live test-run targets `crudforge-client-QA` with operator `crud` / middleware `http://62.84.188.166:31740/`.
+
+## Browser auth compatibility
+
+Password grant uses a **public** client (no secret in the SPA). When `auth.forwardedProto` is set, token and API calls send `X-Forwarded-Proto`. Live apps proxy `/realms` and `/admin/realms` to Keycloak `serverUrl` so token and Admin REST calls avoid browser CORS. Broader `/auth` and `/admin` prefixes are **not** proxied: `/auth` would steal the Fuse sign-in page, and `/admin` would steal Angular admin routes (Keycloak console also lives under `/admin`).
+
+## CI
+
+- `.github/workflows/qa.yml` — PRs: `npm test` + mock Playwright (`test:e2e` ignores `iam-live.spec.js`). No live secrets.
+- `.github/workflows/qa-live.yml` — `workflow_dispatch` / weekly schedule, GitHub environment `keycloak-qa`, repository secrets. Do not enable this on untrusted forks.
+
+## Cleanup
+
+`node cli.js bootstrap --cleanup --preferences e2e/crudforge.iam-live.yml --env-file .env.qa` deletes **only** IDs recorded in `.crudforge/provision-state.json`.
+
+## Live QA results (2026-09-20)
+
+Prerequisites: gitignored `.env.qa`, Keycloak `http://62.84.188.166:30080`, realm `CRUD-FORDGE`, Playwright Chromium with default browser path (`env -u PLAYWRIGHT_BROWSERS_PATH` if a sandbox path is set).
+
+| Check | Result |
+|---|---|
+| Default `auth.provider: none`, `provision.enabled: false` | Pass (`node test/verify.js`) |
+| Env-ref validation and secret stripping | Pass |
+| Bootstrap client `crudforge-client-QA` + roles + users | Pass (native Admin REST; unmanaged client used as-is) |
+| Second bootstrap idempotent, passwords not reset | Pass |
+| Generated live app `tsc --noEmit` | Pass |
+| LIVE-AUTH-01 seeded admin sign-in | Pass |
+| LIVE-AUTH-02 unknown user / bad password rejected | Pass |
+| LIVE-AUTH-03 anonymous redirect to sign-in | Pass |
+| LIVE-AUTH-04 Sign out clears session | Pass |
+| LIVE-RBAC-01 limited user → `/admin/no-access` | Pass |
+| LIVE-API-01 limited user denied Admin REST | Pass |
+| LIVE-API-02 realm operator can GET `/admin/realms/.../users` | Pass |
+| LIVE-IAM-01 ROLE_ADMIN opens User Management shell | Pass |
+| LIVE-IAM-02 realm operator `crud` denied Angular IAM screens | Pass (no `ROLE_ADMIN`) |
+| Admin wrapper `:31740` create client/user/role | **Blocked** (see below) |
+| Combined IAM UI + Admin REST as one seeded user | **Blocked** (see below) |
+
+`npm run test:e2e:iam:live` — **9 passed** (also re-run via `./test-run.sh live` into `/Users/abdulla/Work/CRUD-FORDGE-SETUP/crud-fordge-testing-area`).
+
+`./test-run.sh mock` — generator verify + CRUD + mock IAM **passed** into the same testing area (`.app`, `.iam-app`).
+
+## Blockers
+
+1. **Admin service adapter (`:31740`)**  
+   The wrapper is not the Keycloak Admin REST API. Documented `GET /api/v1/*` requires realm role `KEYCLOAK_ADMIN_ACCESS`. The supplied `crud` user can authenticate to native Keycloak on `:30080` (realm-management) but **does not** have `KEYCLOAK_ADMIN_ACCESS`, so wrapper calls return **403**. Create client/user/role is **not** in that contract. Live bootstrap therefore uses `auth.provision.adapter: keycloak-admin-rest` against `:30080`. Minimum access to use the wrapper: `KEYCLOAK_ADMIN_ACCESS` plus whatever write APIs the service actually exposes (confirm from its HTML API reference; do not assume native Admin REST paths).
+
+2. **`crudforge-client-QA`**  
+   Live QA uses this application client ID. If it already exists unmanaged, bootstrap uses it without modification. Closest legacy public client `crude-fordge-QA` remains untouched.
+
+3. **Single identity for IAM UI + Keycloak Admin REST**  
+   Angular ACL treats `ROLE_ADMIN` as app admin. Keycloak user CRUD needs `realm-management` client roles. Seeded `crudforge-qa-admin` has `ROLE_ADMIN` only (UI shell works; Admin REST as that user is denied). Operator `crud` has realm-management only (Admin REST works; Angular IAM shows “No screens assigned”). We did not grant `realm-admin` to seeded app users and did not add `ROLE_ADMIN` to `crud`. Full in-browser create/edit/delete of users against live Keycloak therefore remains blocked until a dedicated QA user is given **both** sets of roles.
+
+4. **GitHub Actions live job**  
+   `.github/workflows/qa-live.yml` is `workflow_dispatch` / weekly schedule with environment `keycloak-qa`. It is not run on pull requests. Creating that GitHub environment and secrets is an operator step; this session did not execute the hosted live workflow.
+
+## Security review
+
+Independent review requested changes: `stripSecretsForGenerate` must run on the CLI `generate` path so `auth.clientSecret` cannot be embedded in entity `preferences`. Fixed in `src/commands/generate.js` and `src/generator/index.js`, with generator tests that fail if those secrets are emitted.
+

package/QA/PLAN.md

@@ -0,0 +1,43 @@
+# CRUDForge QA plan
+
+**Target:** generated Fuse mock app (`e2e/.app`) at http://127.0.0.1:4200  
+**Build:** `npm run e2e:prepare` then `npm run e2e:serve`  
+**Sign-in:** prefilled `demo@crudforge.com` / click Sign in  
+**Entities under test:** Book, Author  
+**Config under test:** `formMode: sidebar`, `viewMode: table`, `searchMode: field`, mock data on
+
+## Scope
+
+In scope: auth, admin navigation, list table, card toggle, field search, filter drawer, new/edit sidebar forms, validation, detail, delete confirm, pagination, pin/flag, export control presence, Author parity.
+
+Out of scope this pass: real backend APIs, Elasticsearch, page-mode forms, overwrite-policy CLI, generator unit internals (covered by `node test/verify.js`).
+
+## Entry criteria
+
+- `e2e/.app` generated from current templates
+- App serves on port 4200 without compile errors
+- Playwright Chromium installed (`npm run test:e2e:install`)
+
+## Exit criteria
+
+- Every case in `TESTCASES.md` has Pass / Fail / Blocked
+- Failures logged in `RESULTS.md` with severity and repro
+- `npm run test:e2e` matches the automated subset
+- Defects that belong in generator templates are filed against `src/templates`, not `e2e/.app`
+
+## Severity
+
+| Level | Meaning |
+|---|---|
+| S1 | Cannot sign in or open an entity list |
+| S2 | Create/edit/delete wrong surface or data loss |
+| S3 | Feature works but UX/a11y/visual is wrong |
+| S4 | Cosmetic / copy |
+
+## How the QA agent runs a pass
+
+1. Confirm server is up (`e2e:serve`).
+2. Execute automated specs: `npm run test:e2e`.
+3. Walk remaining manual cases in Chromium (Playwright MCP when available).
+4. Update `RESULTS.md` and the QA canvas.
+5. If a generator bug is found, fix `src/templates/**`, re-run `e2e:prepare`, retest.

package/QA/RESULTS.md

@@ -0,0 +1,59 @@
+# QA results — existing features
+
+**Pass date:** 2026-09-05  
+**App:** http://127.0.0.1:4200  
+**Config:** `formMode: sidebar`, `viewMode: table`, `searchMode: field`, mock 12 rows  
+**Runner:** Playwright Chromium (`npm run test:e2e`)
+
+## Summary
+
+| Bucket | Count |
+|---|---|
+| Automated executed | 22 |
+| Automated passed | 22 |
+| Automated failed | 0 |
+| Manual still open | 0 |
+| Defects found | 2 (both fixed in templates on the first pass) |
+
+## Automated results
+
+| ID | Result | Notes |
+|---|---|---|
+| AUTH-01 | Pass | Demo sign-in reaches `/admin` |
+| AUTH-02 | Pass | Logo + Welcome copy. Sign-in button uses Fuse `--theme-color-primary-600` (oklch from `#0f766e`) |
+| NAV-01 | Pass | Book Management + New |
+| NAV-02 | Pass | Author Management + New |
+| LIST-01 | Pass | Mock titles and `of 12` |
+| LIST-02 | Pass | Next page shows 11–12 of 12 |
+| LIST-03 | Pass | Pin row → Unpin row |
+| LIST-04 | Pass | Blue flag applies `tr.has-flag` |
+| LIST-05 | Pass | Export menu: Filtered + All |
+| SEARCH-01 | Pass | Search-by + Search field |
+| SEARCH-02 | Pass | `Mock title 1` keeps 4 rows (`1`, `10`, `11`, `12`); `Mock title 2` gone |
+| FILTER-01 | Pass | Advanced Filters drawer |
+| FILTER-02 | Pass | Title contains `Mock title 1` closes drawer and yields `1 – 4 of 4` |
+| FORM-01 | Pass | New stays on list, sidebar New Book |
+| FORM-02 | Pass | Edit stays on list, sidebar Edit Book |
+| FORM-03 | Pass | Save disabled without required title |
+| FORM-04 | Pass | Cancel closes drawer |
+| FORM-05 | Pass | Author New is sidebar |
+| DETAIL-01 | Pass | `/admin/book/:id/view` |
+| DETAIL-02 | Pass after fix | First run 404 — see DEF-01 |
+| DELETE-01 | Pass | Cancel keeps Mock title 1 |
+| CARD-01 | Pass after fix | First run could not find toggle — see DEF-02 |
+
+## Defects
+
+### DEF-01 — S2 Detail Back 404 (fixed)
+
+- **Case:** DETAIL-02  
+- **Repro:** View a book, click Back.  
+- **Was:** navigated to `/admin/book/:id` (no route) → 404.  
+- **Cause:** `goBack()` used `../` from `:id/view`.  
+- **Fix:** `src/templates/angular/entity/components/presentation/detail/_entity_-detail.component.ts.ejs` now navigates `../../`.
+
+### DEF-02 — S3 View/filter icon buttons had no accessible name (fixed)
+
+- **Case:** CARD-01  
+- **Repro:** `matTooltip` is not a DOM attribute, so the card toggle was not findable by name.  
+- **Fix:** aria-label on view-mode and filter buttons in `_entity_-actions.component.html.ejs`.