@pega/sdk 0.0.13 → 0.0.15

package/templates/react-sdk-reference/.ai-common/skills/portal-flow/run-and-verify-portal.md

@@ -0,0 +1,290 @@
+# Skill: Run and Verify the Portal
+
+Prove that the generated portal actually runs — by building it, signing in, opening every page, walking a case to its end, and comparing the result with the same portal running on the Pega server — and repair what breaks.
+
+---
+
+## Purpose
+
+A passing build is not a working portal. A portal can compile cleanly and still show a placeholder instead of its header, a blank widget, a broken case step, or a form whose layout drifts from Pega's. This skill closes that gap so the user is not the one who discovers the failure.
+
+Use this at the end of every portal flow, after the calling prompt's build step passes. It is the terminal step of that prompt.
+
+---
+
+## Rules for this skill
+
+**Portal projects only.** This skill verifies an application that renders a full Pega portal. If the project instead hosts an embedded case flow inside an existing application, use `{{SKILL_DIR}}/embedded-flow/run-and-verify-integration{{SKILL_EXT}}` and stop here.
+
+**Resolve, never assume.** Every command comes from the project — its script manifest, its toolchain configuration, its own output. Do not assume a package manager, a framework, a build tool, a port, a route, or a script name. If a needed capability has no script entry, derive the invocation from the tool the project already depends on rather than adding a script.
+
+**Assert behaviour, not implementation.** The stages below describe _what must be true_. Write the checks in whatever form suits the project. Do not treat any wording here as a template to transcribe.
+
+**Never handle credentials.** A human signs in, in a browser window you open. Credentials are never requested, captured, logged, echoed, or written to any file by the agent, in any stage, under any failure condition.
+
+**Tell the user where you are, in plain words.** Announce each stage as it starts, counting only the stages that run — "Trying it out — part 4 of 7: Checking every page". Use these names: Stage 1 "Checking the code", Stage 2 "Opening your app", Stage 3 "Signing in", Stage 4 "Checking every page", Stage 5 "Walking through a case", Stage 6 "Comparing with your Pega portal", Stage 7 "Fixing what failed".
+
+**You run every stage yourself, in this conversation.** Start right after the build passes, without asking first. Open the browser, drive the portal, check the results, and repair what fails. The human's only parts are signing in, answering the case question in Stage 5, and supplying a value a case step needs that you cannot invent. Never hand a stage back to the user and end your turn, and never ask them to open the portal in their own browser to try it.
+
+**Never lighten a stage.** Do not replace a stage with a smaller or cheaper check because the run is long, the component count is large, or a stage needs a human for a moment. Stop early only for the reasons listed in [Stopping early](#stopping-early).
+
+---
+
+## Inputs from the calling prompt
+
+Use whatever the calling prompt hands over; none of it is required.
+
+- **The generated components**, and for each one the landing page or case type it came from — used for the coverage report in Stage 4
+- **The portal** chosen from the server — used in Stage 1 and Stage 6
+- **The case types** the user selected — used in Stage 5 instead of asking which ones to try
+
+---
+
+## Stage 1 — Static gates
+
+No browser, no credentials.
+
+1. **Production build.** Resolve and run the project's production build.
+2. **Type check.** Run the project's type-check entry point. If it has none, invoke the type checker the project already depends on in a no-emit mode using the project's own compiler configuration. Do not add a script entry for this.
+3. **Lint.** If the project has a lint entry point, run it over every file the calling prompt created or edited and fix every error in those files. If many still remain after one repair pass, list them grouped by rule and ask the user whether to keep fixing or to continue with them noted in the summary. If the project has no lint entry point, note that and move on.
+4. **Configuration coherence.** Read the served SDK configuration file and assert that the Pega server address and `portalClientId` are present and non-empty, and that `appPortal` is set. When the calling prompt chose a portal from the server, assert `appPortal` equals that portal's value. An empty `portalClientId` makes the redirect sign-in hang with no network activity and no error.
+
+All of these must pass before continuing, apart from lint errors the user chose to note rather than fix.
+
+---
+
+## Stage 2 — Pre-authentication browser checks
+
+### Choosing a browser driver
+
+Use either of these, in this order of preference:
+
+1. A browser automation library already present in the project's dependency manifest.
+2. Your AI tool's own browser control, if it has one that can show a window the human can sign in to and keep watching the page while they do.
+
+Only when neither is available, add a browser automation library as a development dependency. Ask before adding it, in plain words — "I need a browser-testing tool to try the portal. Can I add one to your project?" If the user declines, stop per [Stopping early](#stopping-early).
+
+### Starting the application
+
+Start the project's development server and **discover its address from the server's own startup output**. Do not assume a port. Find the route that renders the portal from the project's own router or entry module — the route whose root starts the Pega runtime in portal mode.
+
+If the Pega server named in the SDK configuration is unreachable from this environment, stop here. Report that verification is limited to Stage 1, state which host could not be reached, and do not present the run as a failure of the portal.
+
+### Checking the Pega server accepts this application's address
+
+Run the same CORS preflight check as `{{SKILL_DIR}}/embedded-flow/run-and-verify-integration{{SKILL_EXT}}`, Stage 2 — an `OPTIONS` request with no credentials, the application's real origin as `Origin`, against the SDK's bootstrap API path. If it fails, stop before Stage 3 and report it as a server setting — see [What must only be reported](#what-must-only-be-reported).
+
+### Checks
+
+Load the portal route **in the browser** and assert:
+
+1. The route renders — no server-render failure, no error overlay
+2. The browser console and page-error channels are clean; collect anything that appears
+3. The SDK configuration file, the runtime shell (`/constellation/bootstrap-shell.js`), and the library manifest (`/constellation/lib_asset.json`) resolve as JSON, a script, and JSON — **not as the application's HTML**
+4. The page navigates to the Pega sign-in page. If Pega answers with an error about the redirect address instead, that is a server setting — report it, never change the application for it
+
+Fetching the route over plain HTTP is a useful quick pre-check, but it never satisfies this stage.
+
+---
+
+## Stage 3 — Authentication handoff
+
+The portal signs in by redirecting the whole window to Pega and back.
+
+1. Run the browser in a mode the human can see and interact with
+2. When the Pega sign-in page appears, print a clear, unmissable instruction — for example: "Please sign in to Pega in the window that just opened. I'll carry on by myself once you're signed in."
+3. Wait for the window to return to the application's origin and the portal to move past its loading state, with a timeout generous enough for a person to find credentials and complete any second factor. Keep waiting in this same turn
+4. Persist the browser session state afterwards to `.pega-verify/` at the project root, so later runs may skip this stage
+
+⚠️ **The saved file contains live session tokens.** Before writing it, add an ignore rule for `.pega-verify/` to the project's version-control ignore file and confirm the rule is in place. Never commit the file, and never print its contents.
+
+Session-state reuse is best-effort. If Pega asks to sign in again, run this stage again — that is not a failure. **At least one full pass must start from a session with no saved state**, because only a first sign-in exercises the redirect and the return to the portal.
+
+---
+
+## Stage 4 — Checking every page
+
+### The portal frame
+
+Assert the frame the portal draws around every page is present: the header, the application name or logo, the signed-in user's initials or avatar, and the navigation. A placeholder in place of any of these is a missing frame component — see the fallback check below.
+
+### Every page
+
+Open the home page, then every page in the portal's navigation, one by one, using the navigation itself. On each page assert:
+
+1. **No fallback markers.** An element carrying the `data-pega-fallback` attribute is a placeholder for a component the runtime requested but could not resolve; the attribute's value names it. If the project's fallback component predates that attribute, look for a block showing a bare component name followed by a dump of its properties. Assert there are none
+2. **Console clean.** No errors, including a "maximum update depth" error or any other sign of a render loop
+3. **No failed Pega calls.** No Pega API request answered with a 4xx or 5xx status, and no single request repeated over and over
+4. **No endless loading.** Every loading indicator resolves
+5. **No broken images.** Every image on the page loaded
+6. **No raw values on screen.** No visible text such as `@L`, `@P`, `undefined`, `null`, or `[object Object]`
+7. **Widgets show something.** Every widget shows its data or its own empty state — never a blank box
+8. **The look checks hold** — see [Look checks](#look-checks)
+
+After the last page, reload the portal and assert it returns to the portal without asking to sign in again and without a redirect loop.
+
+### Coverage
+
+When the calling prompt handed over where each generated component came from, report every generated component whose page was never opened, or whose case type is not walked in Stage 5, as **not exercised**. Not exercised is a gap in the run, not a failure.
+
+---
+
+## Stage 5 — Walking through a case
+
+### Choosing the case types
+
+- If the calling prompt passed the case types the user selected, use those.
+- Otherwise, read the case types the portal offers — its Create menu or its quick-create tiles — and ask the user, as a checkbox list, which ones to walk through. Allow choosing none.
+
+Ask once, in the same question, for consent: "This creates real test cases on your Pega server." If the user chooses none or declines, mark this stage **not run** with that reason.
+
+### For each chosen case type
+
+1. **Start it from the portal.** Use the portal's own create entry — the Create menu or a quick-create tile — never a direct API call. Assert the first step renders with its title, its fields, and its action buttons, and no fallback markers
+2. **Check validation once.** On the first step, submit with a required field empty and assert the validation message appears. Run the [Look checks](#look-checks) with the message showing
+3. **Fill the step.** Fill every visible required field with a plausible test value: valid for the field's type and format, the first available option for a list, today's date for a date. Never use real personal data. Assert each value is still there after the field loses focus
+4. **Submit and follow the case.** After each submit, the portal shows one of three things:
+   - **The next form opens directly** (perform mode) — the next assignment is yours. Fill it and continue
+   - **The case opens in review mode with an assignment that offers a Go button** — the next assignment is routed elsewhere. Select Go and continue
+   - **A confirmation, or the case shows as resolved** — the case is complete
+5. **Check read-only screens.** Wherever the case shows entered values back — review screens, summaries, the confirmation — assert they show what was entered, not empty slots
+6. **Run the look checks on every step** — see [Look checks](#look-checks)
+
+Stop a case early, record where it stopped and why, and continue with the next case type when:
+
+- No Go action is offered, or the server refuses access to the next assignment
+- A step needs a file or a specific value you cannot invent. Ask the user once for it; if they cannot supply it, stop that case
+- The case has passed twenty steps without completing
+
+After every case type, return to the home page and continue.
+
+---
+
+## Stage 6 — Comparing with your Pega portal
+
+Open the same portal on the Pega server, in a second window of the same browser: `{infinityRestServerUrl}/app/{appAlias}/`, using both values from the SDK configuration. Confirm it is the same portal by its application name and navigation. If `appAlias` is empty, or the portal that opens is a different one, ask the user for the address they normally open this portal from. If Pega asks to sign in, run the Stage 3 handoff in that window.
+
+Compare every page opened in Stage 4, and the first step of every case type walked in Stage 5, at the **same viewport width** in both windows — first at a desktop width, then at the narrow width used by the look checks.
+
+### Content must match
+
+The application name, the navigation labels and their order, page headings, the widgets on each page, the case types offered for creation, and for each case step its title, field labels and their order, and action button labels. A difference that comes from a generated component dropping or adding something is a defect — repair it per Stage 7. A difference that comes from data — counts, dates, list contents — is reported only.
+
+### Layout must match
+
+Pair each element in the generated portal with the same element in the Pega portal by its visible label or text: fields, section headings, widgets, and action buttons. Elements that exist on only one side are already covered by the content check — skip them here.
+
+- **Structure — must match.** The number of columns in each region, which fields share a row, the order of widgets on a page, and which side the action buttons sit on. A difference is a defect — repair it per Stage 7
+- **Gaps — must be within tolerance.** Measure the gap between each pair of neighbours — field to field, label to input, section to section, widget to widget, button to button — on both sides. The tolerance is the larger of 4px and 25% of Pega's gap. A gap outside the tolerance is a defect — repair it per Stage 7 and measure again. A gap inside it is reported only
+- **Sizes and widths — report only.** List each difference with both values
+
+### Visual differences — report only
+
+Capture side-by-side screenshots of each compared page and step, and list differences in font size, colour, border, and corner radius with both values. These come from the chosen design system and are never forced.
+
+---
+
+## Look checks
+
+Run these on every page in Stage 4 and every case step in Stage 5, first at a desktop width and then at a narrow width of about 375px.
+
+- **Must match — one font family and one base text colour across the whole portal,** and both equal to the values the design system's theme sets. Generated components inherit both, so a difference is a defect — repair it per Stage 7
+- **Must hold:**
+  - No two visible elements overlap
+  - Nothing is wider than its area, so no horizontal scrolling appears
+  - Fields in the same column share a left edge
+  - At the narrow width, multi-column layouts stack into one column and the navigation collapses into a menu
+  - The header never covers page content
+  - Action buttons are fully visible and not clipped
+
+  A failure is a defect — repair it per Stage 7
+
+- **Report only:** font sizes, accent colours, borders, corner radius, and spacing, each with its measured value. Gaps are enforced only by the comparison in Stage 6
+- **Quick accessibility checks — report only:** every input has a visible or programmatic label, keyboard focus is visible, and the action buttons can be reached with the keyboard
+
+---
+
+## Stage 7 — Triage and repair
+
+### What may be fixed
+
+Only code the calling prompt generated or edited, the component map, and the design system's provider and global styles.
+
+| Symptom                                                                    | Cause                                                                                                        | Fix                                                                                                                                     |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| A fallback marker appears                                                  | The named component is absent from the registry                                                              | Add the registry entry, generating the component if it does not exist                                                                   |
+| Type or lint failure in a generated component                              | Generated code does not satisfy the project's toolchain                                                      | Correct the generated file                                                                                                              |
+| A widget is blank, or a page or step stays loading                         | A generated component reads the wrong input or skips its own empty state                                     | Correct the generated component against its skill file                                                                                  |
+| A value is lost after the field loses focus                                | The generated field holds local state without committing it                                                  | Correct the commit inside the generated field                                                                                           |
+| Different font family or base text colour                                  | A generated component sets its own, or the design system's provider or global styles are missing             | Remove the override, or add the provider or global styles                                                                               |
+| Elements overlap, overflow, or misalign, or fail to stack when narrow      | A generated field adds its own margins, fixed sizes, or positioning, or a layout template stacks incorrectly | Correct the generated field or layout template                                                                                          |
+| Column count, row grouping, widget order, or button side differs from Pega | A generated layout template arranges its children differently from its skill file                            | Correct the generated layout template                                                                                                   |
+| A gap differs from Pega's by more than the tolerance                       | A generated layout template or field sets the wrong spacing                                                  | Correct the spacing using the design system's spacing tokens; use a fixed pixel value only when the design system has no spacing tokens |
+| A label, heading, or button from Pega is missing or extra                  | A generated component drops or adds content                                                                  | Correct the generated component against its skill file                                                                                  |
+
+After every fix, run Stage 1 again, then re-run the check that failed.
+
+### What must only be reported
+
+**Never fix these. Stop and hand back.**
+
+- Anything requiring credentials or server configuration — the server address, the application alias, the client identifier, the portal name, a case type that does not exist, authorization refused
+- **A Pega CORS policy that does not allow this application's address.** Report it exactly as `{{SKILL_DIR}}/embedded-flow/run-and-verify-integration{{SKILL_EXT}}` describes under "What must only be reported", including the plain message for the user
+- **A redirect address the Pega server does not accept** for this client. Tell the user, in plain words, to ask their Pega administrator to add the application's address to that client's allowed redirect addresses
+- Case routing, permissions, and server-side validation or data rules
+- Images or other files the Pega server itself fails to serve
+- Anything in the SDK adapter package, the authentication or bootstrap code, or the event helper module. Report the file, the symptom, and the likely cause
+- Any visual difference beyond the must-match and must-hold checks above
+
+### The loop
+
+Fix, re-run the stage that failed, continue. Cap the number of repair cycles at three attempts per failing check. On exhausting the cap, or on reaching any report-only class, hand back with the captured evidence and a specific diagnosis rather than continuing to try variations.
+
+Capture a screenshot and the collected console output for every failed check, and store them in `.pega-verify/`.
+
+### Stopping early
+
+Stop before Stage 4 has run only for one of these reasons, and always finish with the verification summary:
+
+- The Pega server is unreachable from this environment (Stage 2)
+- The Pega server does not allow this application's address, or does not accept its redirect address (Stage 2, or after sign-in)
+- No browser can be used: the tool's own browser cannot show the sign-in and the user declined adding a browser automation library
+- The sign-in was not completed before the Stage 3 timeout
+- A report-only failure was reached, or the repair cap was exhausted
+
+Anything else — the run being long, many pages, many components, a stage needing a human for a moment — is not a reason to stop.
+
+### Signing off
+
+After everything else, sign out through the portal's own menu and assert the window returns to the Pega sign-in page. Report the result; do not repair it.
+
+---
+
+## Verification summary
+
+Always finish by reporting, whatever the outcome:
+
+- Which stages ran and which passed — mark each stage **passed**, **fixed**, or **not run**, with the reason for any stage not run
+- The pages opened, and each case type walked with how far it got and why it stopped, if it stopped early
+- Every fix applied, with the file and the reason
+- The components not exercised
+- The report-only differences from Stage 6 and the look checks, with the screenshots' location
+- Everything that needs the user or their Pega administrator, stated as a concrete action
+- The furthest stage reached, so "done" is never ambiguous between _generated_ and _verified_. If Stage 4 or Stage 5 did not run, say plainly "**Not verified yet**", give the reason, and say what the user can do next
+
+---
+
+## Common failures in portals
+
+| Symptom                                                                 | Cause                                                                                                                  |
+| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| A placeholder named `AppShell` instead of the header and navigation     | The portal frame components were not generated or not registered                                                       |
+| The header shows but the navigation or Create menu is empty             | The frame component keeps its own copy of the page or case type list instead of passing its inputs through             |
+| Stuck on loading after sign-in, with a CORS error on a Pega call        | The Pega CORS policy for the most specific matching endpoint does not list the application's origin — a server setting |
+| Pega shows an error about the redirect address instead of the sign-in   | The application's address is not an allowed redirect address for the client — a server setting                         |
+| Sign-in hangs with no network activity                                  | `portalClientId` is empty                                                                                              |
+| A different portal opens                                                | `appPortal` does not match the portal chosen from the server                                                           |
+| A widget is a blank box                                                 | The widget's data request failed, or the generated widget skips its empty state                                        |
+| Broken image icons on tiles or in the header                            | The image address is built wrongly by a generated component, or the Pega server does not serve that image              |
+| Fields line up in a different number of columns from Pega               | The generated layout template ignores its column configuration                                                         |
+| Gaps between fields or sections are visibly tighter or looser than Pega | The generated layout template or field sets its own spacing instead of the design system's spacing tokens              |

package/templates/react-sdk-reference/.ai-common/skills/template-components.md

@@ -48,7 +48,7 @@ This pattern is design-system agnostic — the grid/flex section must be replace
 >
 > **Use plain CSS grid** (`display: grid; grid-template-columns; width: 100%`) for all layout templates. The `templateCol` input value (e.g., `'1fr 1fr'`, `'2fr 1fr'`) maps directly to `grid-template-columns`. Do NOT use DS grid components — they may have max-width constraints.
 
-**1. Check the component-specific skill file** — `{{SKILL_DIR}}/template-skills/<ComponentName>.md` contains a **Design System Mapping** section where available. Use it as a starting point.
+**1. Check the component-specific skill file** — `{{SKILL_DIR}}/template-skills/<ComponentName>{{SKILL_EXT}}` contains a **Design System Mapping** section where available. Use it as a starting point.
 
 **2. If the chosen design system is not covered** — use the **component purpose** description to identify the appropriate DS layout primitive (grid, flex, columns).
 
@@ -109,6 +109,18 @@ Used for: CaseView, DefaultPage, ObjectPage, AppShell, Confirmation
 
 ---
 
+## Visual Preservation
+
+When replacing an existing implementation, the replacement must look the same as the original:
+
+1. **Read the component's companion style file first** (for example a `.css` file in its folder). Note every class's visual intent — spacing, sizing, colours, and layout.
+2. Reproduce that intent through the new design system's layout inputs, inline styles, or by keeping the style import — whichever gives the closest match.
+3. Never silently drop legacy layout utility classes — map each one to an equivalent style, keeping column gaps, padding, and alignment.
+
+In the embedded flow there is no original to preserve: the customer's look, recorded in the Design Profile, decides instead.
+
+---
+
 ## Rendering Children
 
 Templates use three patterns to render child components: