@pega/sdk 0.0.12 → 0.0.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +32 -11
- package/package.json +1 -1
- package/templates/react-sdk-reference/.ai-common/agents/embedded-flow-expert.md +9 -9
- package/templates/react-sdk-reference/.ai-common/global/ai-agent-instructions-embedded.md +2 -2
- package/templates/react-sdk-reference/.ai-common/global/ai-agent-instructions.md +1 -1
- package/templates/react-sdk-reference/.ai-common/instructions/dse-component.md +1 -1
- package/templates/react-sdk-reference/.ai-common/instructions/embedded-component.md +1 -1
- package/templates/react-sdk-reference/.ai-common/instructions/field-component.md +1 -1
- package/templates/react-sdk-reference/.ai-common/instructions/infra-component.md +1 -1
- package/templates/react-sdk-reference/.ai-common/instructions/template-component.md +1 -1
- package/templates/react-sdk-reference/.ai-common/instructions/widget-component.md +1 -1
- package/templates/react-sdk-reference/.ai-common/prompts/embedded-component-manifest.md +2 -2
- package/templates/react-sdk-reference/.ai-common/prompts/generate-all-components.md +1 -1
- package/templates/react-sdk-reference/.ai-common/prompts/generate-embedded-components.md +10 -11
- package/templates/react-sdk-reference/.ai-common/skills/connect-pega-server.md +84 -31
- package/templates/react-sdk-reference/.ai-common/skills/embedded-flow/analyze-customer-repo.md +11 -2
- package/templates/react-sdk-reference/.ai-common/skills/embedded-flow/wire-integration.md +6 -6
package/README.md
CHANGED
|
@@ -134,13 +134,29 @@ The generated project is ready to run and includes:
|
|
|
134
134
|
|
|
135
135
|
The scaffolded project ships with `sdk-config.json` and a generated MCP config file
|
|
136
136
|
both intentionally blank/placeholder — connection details are never collected at
|
|
137
|
-
scaffold time.
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
137
|
+
scaffold time. The same setup applies to full-portal and embedded projects.
|
|
138
|
+
|
|
139
|
+
**AI coding assistant (recommended):** the first workflow that needs a live Pega
|
|
140
|
+
server checks the active `sdk-config.json`, the generated MCP config, and project-root
|
|
141
|
+
`.env*` files. It asks once for every missing non-secret value. You can provide those
|
|
142
|
+
values in chat or update an allowed file yourself; the assistant then synchronizes
|
|
143
|
+
all applicable destinations and asks again only for values that remain missing.
|
|
144
|
+
|
|
145
|
+
**Manual or environment setup:** configure the following non-secret values in any
|
|
146
|
+
applicable source:
|
|
147
|
+
|
|
148
|
+
| Value | Environment key example | `sdk-config.json` | MCP config |
|
|
149
|
+
| --------------------- | ----------------------- | ----------------------------------------------------------- | -------------------------------------- |
|
|
150
|
+
| Pega server URL | `PEGA_INFINITY_URL` | `serverConfig.infinityRestServerUrl` | `{InfinityURL}` in the URL |
|
|
151
|
+
| Application alias | `PEGA_APP_ALIAS` | `serverConfig.appAlias` | `{AppAlias}` in the URL |
|
|
152
|
+
| MCP rule name | `PEGA_MCP_RULE_NAME` | — | `{MCPRuleName}` in the server key |
|
|
153
|
+
| MCP rule instance key | `PEGA_MCP_RULE_INS_KEY` | — | `{MCPRuleInsKey}` in the URL |
|
|
154
|
+
| OAuth client ID | `PEGA_CLIENT_ID` | `authConfig.mashupClientId` and `authConfig.portalClientId` | Cursor's `auth.clientId`, when present |
|
|
155
|
+
|
|
156
|
+
For full-portal projects, use the scaffolded application `sdk-config.json`. For
|
|
157
|
+
embedded projects, use the copy in the host framework's browser-served static
|
|
158
|
+
directory (for example `public/sdk-config.json`), not a stale same-named root copy.
|
|
159
|
+
Its relevant structure is:
|
|
144
160
|
|
|
145
161
|
```jsonc
|
|
146
162
|
{
|
|
@@ -163,10 +179,15 @@ scaffold time. There are two ways to fill them in:
|
|
|
163
179
|
- `appAlias` — the application alias to load
|
|
164
180
|
- `mashupClientId` / `portalClientId` — OAuth 2.0 client IDs registered in Pega
|
|
165
181
|
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
182
|
+
The generated MCP file is `.vscode/mcp.json` for Copilot, `.cursor/mcp.json` for
|
|
183
|
+
Cursor, or `.mcp.json` for Claude Code. Copilot and Claude Code use URL-only MCP
|
|
184
|
+
configuration and do not require a client secret. Cursor's authenticated MCP entry
|
|
185
|
+
also requires `auth.clientId` and `auth.clientSecret`. The Pega MCP client secret
|
|
186
|
+
must come from a private project-root environment variable such as
|
|
187
|
+
`PEGA_CLIENT_SECRET`; never provide it in chat, use a browser-exposed environment
|
|
188
|
+
name (`VITE_*`, `NEXT_PUBLIC_*`, `REACT_APP_*`, or `EXPO_PUBLIC_*`), or put it in
|
|
189
|
+
browser-served `sdk-config.json`. The assistant reads the private environment value
|
|
190
|
+
and writes it only to Cursor's `auth.clientSecret`.
|
|
170
191
|
|
|
171
192
|
## Available Scripts
|
|
172
193
|
|
package/package.json
CHANGED
|
@@ -55,7 +55,7 @@ Determine which workflow governs the request, then execute it by reading the ref
|
|
|
55
55
|
|
|
56
56
|
### Step 0.0 — Ensure the Pega server connection is configured
|
|
57
57
|
|
|
58
|
-
Before executing any data source below, read and execute `{{SKILL_DIR}}/connect-pega-server.md`. It is a no-op when the connection is already configured,
|
|
58
|
+
Before executing any data source below, read and execute `{{SKILL_DIR}}/connect-pega-server.md`. It is a no-op when the connection is already configured. Otherwise, it resolves existing values from the active MCP config, browser-served `sdk-config.json`, and environment files, then asks once for every missing non-secret value. The user may provide those values in chat or write them into any allowed configuration file named by the gate; the assistant re-reads the files and synchronizes every applicable destination. The gate may pause for an environment-sourced Pega MCP client secret (Cursor only) or an MCP reconnect. After the user retries, rerun the gate before executing any data source.
|
|
59
59
|
|
|
60
60
|
### Step 0.1 — Check for a case type in the prompt
|
|
61
61
|
|
|
@@ -127,13 +127,13 @@ Step 0 of the wire-integration skill resolves both, checks whether the named con
|
|
|
127
127
|
|
|
128
128
|
If the user named a launch point but no render target, the skill infers it from what the control already does. If they named neither, the skill asks using surfaces drawn from the customer's own application. Never assume either one.
|
|
129
129
|
|
|
130
|
-
| Workflow | Required inputs
|
|
131
|
-
| ------------------ |
|
|
132
|
-
| Analyze | Case type class + access to the customer's codebase
|
|
133
|
-
| Generate | Case type class + component list + Design Profile (or permission to create one)
|
|
134
|
-
| Full embedded flow | Case type class + server-resolved component list + codebase access + launch point + render target
|
|
135
|
-
| Wire integration | Case type class + generated
|
|
136
|
-
| Verify integration | A wired integration + a human available to authenticate when the flow reaches the Pega login form
|
|
130
|
+
| Workflow | Required inputs |
|
|
131
|
+
| ------------------ | --------------------------------------------------------------------------------------------------------------------------- |
|
|
132
|
+
| Analyze | Case type class + access to the customer's codebase |
|
|
133
|
+
| Generate | Case type class + component list + Design Profile (or permission to create one) |
|
|
134
|
+
| Full embedded flow | Case type class + server-resolved component list + codebase access + launch point + render target |
|
|
135
|
+
| Wire integration | Case type class + generated components folder (location resolved during analysis) must exist + launch point + render target |
|
|
136
|
+
| Verify integration | A wired integration + a human available to authenticate when the flow reaches the Pega login form |
|
|
137
137
|
|
|
138
138
|
---
|
|
139
139
|
|
|
@@ -143,7 +143,7 @@ If the user named a launch point but no render target, the skill infers it from
|
|
|
143
143
|
2. **Always read before executing** — read the skill or prompt file fully before acting on it. Never paraphrase from memory.
|
|
144
144
|
3. **Follow steps in order** — each skill/prompt defines numbered steps. Execute them sequentially without skipping.
|
|
145
145
|
4. **Design Profile is the bridge** — the analysis skill produces it, the generation prompt consumes it. If generation is requested and no profile exists, analysis must run first. Step 0 of the wiring skill consumes it too, when it has to ask where the flow should render — which is why analysis precedes that gate rather than following it.
|
|
146
|
-
5. **Never modify the customer's existing code** except at the seams that the wiring and verification skills enumerate. The
|
|
146
|
+
5. **Never modify the customer's existing code** except at the seams that the wiring and verification skills enumerate. The generated components folder (location resolved during analysis and recorded in the Design Profile) is purely additive, and a failing verification check is never permission to edit customer code outside those seams to make it pass.
|
|
147
147
|
6. **Component skills are authoritative** — the behavioral contracts in `{{SKILL_DIR}}/field-skills/`, `template-skills/`, `widget-skills/`, `design-system-extension-skills/`, and `infra-skills/` define what each component must do. These are non-negotiable.
|
|
148
148
|
7. **Adapt to the customer's framework** — the skills and prompts are framework-agnostic. Determine the customer's framework from their project configuration and apply conventions accordingly.
|
|
149
149
|
8. **Verification is mandatory, and it is not only static** — the generation prompt's checks confirm the generated files are well-formed. They do not confirm the flow runs. Whenever the integration has been wired, finish with `{{SKILL_DIR}}/embedded-flow/run-and-verify-integration.md` and report how far it got. Never declare success on static checks alone.
|
|
@@ -47,7 +47,7 @@ Pega SDK packages (`.tgz` files) have been added to the project root and referen
|
|
|
47
47
|
|
|
48
48
|
### SDK Configuration
|
|
49
49
|
|
|
50
|
-
`sdk-config.json` contains connection details
|
|
50
|
+
The browser-served `sdk-config.json` contains non-secret Pega server connection details. The first workflow that needs a live server runs `{{SKILL_DIR}}/connect-pega-server.md`, which resolves values from the active SDK config, MCP config, and environment files, then asks once for all missing non-secret values. The user may provide those values in chat or update an allowed file; the assistant synchronizes every applicable destination. Only a Cursor-style MCP entry requires a Pega MCP client secret, which must come from a private environment variable and is never requested in chat or written to `sdk-config.json`. The browser SDK's OAuth grant configuration remains the user's choice. The case type is resolved from the server during the embedded flow itself.
|
|
51
51
|
|
|
52
52
|
---
|
|
53
53
|
|
|
@@ -100,7 +100,7 @@ Most infrastructure components ship from the SDK and are never generated. Three
|
|
|
100
100
|
|
|
101
101
|
## 5. Rules
|
|
102
102
|
|
|
103
|
-
1. **Never modify the customer's existing components during analysis or generation** — the
|
|
103
|
+
1. **Never modify the customer's existing components during analysis or generation** — the generated components folder (location resolved during analysis and recorded in the Design Profile) is additive. Wiring is the exception: it edits the integration seams listed in the wire-integration skill, plus the verification tooling seams listed in the run-and-verify-integration skill. A failing verification check never widens that set
|
|
104
104
|
2. **Match the customer's conventions** — generated code should look like the customer wrote it
|
|
105
105
|
3. **Satisfy the Pega behavioral contract** — every component must implement what its skill file requires
|
|
106
106
|
4. **Use the customer's design system** — never introduce a new UI library
|
|
@@ -10,7 +10,7 @@ This is a **reference implementation** — not a framework. The UI components (f
|
|
|
10
10
|
|
|
11
11
|
### SDK Configuration
|
|
12
12
|
|
|
13
|
-
`sdk-config.json` and the generated MCP config file are scaffolded blank/placeholder — connection details are never collected at scaffold time. The
|
|
13
|
+
`sdk-config.json` and the generated MCP config file are scaffolded blank/placeholder — connection details are never collected at scaffold time. The first workflow that needs a live Pega server runs `{{SKILL_DIR}}/connect-pega-server.md`, which resolves values from the active SDK config, MCP config, and environment files, then asks once for all missing non-secret values. The user may provide those values in chat or update an allowed file; the assistant synchronizes every applicable destination. A Pega MCP client secret is required only when the active MCP entry has `auth.clientSecret` (currently Cursor), must come from a private environment variable, and is never requested in chat or written to browser-served SDK configuration.
|
|
14
14
|
|
|
15
15
|
---
|
|
16
16
|
|
|
@@ -10,7 +10,7 @@ When generating or modifying Pega components in the `pega-components/` folder (c
|
|
|
10
10
|
|
|
11
11
|
## Context
|
|
12
12
|
|
|
13
|
-
These components are different from the reference app's sample components. They are generated to live **inside a customer's existing project**, using the customer's design system so that they are visually indistinguishable from the rest of their UI. The Design Profile (
|
|
13
|
+
These components are different from the reference app's sample components. They are generated to live **inside a customer's existing project**, using the customer's design system so that they are visually indistinguishable from the rest of their UI. The Design Profile (`docs/design-profile.md` at the project root) describes the customer's visual conventions.
|
|
14
14
|
|
|
15
15
|
---
|
|
16
16
|
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
ai-globs: **/
|
|
2
|
+
ai-globs: **/{AutoComplete,CancelAlert,Checkbox,Currency,Date,DateTime,Decimal,Dropdown,Email,Group,Integer,Location,Multiselect,ObjectReference,Percentage,Phone,RadioButtons,RichText,ScalarList,SelectableCard,SemanticLink,TextArea,TextContent,TextInput,Time,URL,UserReference}/**/*
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# Field Component Rules
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
ai-globs: **/
|
|
2
|
+
ai-globs: **/{AdvancedSearch,AppShell,BannerPage,CaseSummary,CaseView,CaseViewActionsMenu,Confirmation,DataReference,DefaultForm,DefaultPage,Details,FieldGroupTemplate,HierarchicalForm,InlineDashboard,InlineDashboardPage,ListPage,ListView,MultiReferenceReadOnly,NarrowWide,ObjectPage,OneColumn,PromotedFilters,SelfServiceCaseView,SimpleTable,SingleReferenceReadOnly,SubTabs,TwoColumn,WideNarrow,WssNavBar,SearchForm,SearchGroups}/**/*
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# Template Component Rules
|
|
@@ -105,7 +105,7 @@ Record the visual treatment only. Generated components read validation messages
|
|
|
105
105
|
|
|
106
106
|
### 4. File Conventions
|
|
107
107
|
|
|
108
|
-
**Context only.** Generated components use Pega-owned paths and names (`
|
|
108
|
+
**Context only.** Generated components use Pega-owned paths and names (`{output_path}/{ComponentName}/`), so Structure and Naming below do not apply to them. Re-exports, test location, and style location still inform co-located files.
|
|
109
109
|
|
|
110
110
|
| Field | Description |
|
|
111
111
|
| -------------- | ------------------------------------------------------- |
|
|
@@ -126,7 +126,7 @@ Record the visual treatment only. Generated components read validation messages
|
|
|
126
126
|
| Default/named preference | Which import style dominates |
|
|
127
127
|
| Style imports | How stylesheets or style modules are imported |
|
|
128
128
|
|
|
129
|
-
Generated components import the customer's UI primitives through their path aliases. Relative paths are used only _within_ `
|
|
129
|
+
Generated components import the customer's UI primitives through their path aliases. Relative paths are used only _within_ the generated output folder (`{output_path}`) — for shared helpers, barrel files, and the registry file's component imports. One Pega component is never imported into another to render it; that always goes through the component registry.
|
|
130
130
|
|
|
131
131
|
---
|
|
132
132
|
|
|
@@ -57,7 +57,7 @@ Once design system, base folder, and type scope are resolved, continue to Step 0
|
|
|
57
57
|
|
|
58
58
|
### 0.5.0 — Ensure the Pega server connection is configured
|
|
59
59
|
|
|
60
|
-
Before executing any data source below, read and execute `{{SKILL_DIR}}/connect-pega-server.md`. It is a no-op when the connection is already configured,
|
|
60
|
+
Before executing any data source below, read and execute `{{SKILL_DIR}}/connect-pega-server.md`. It is a no-op when the connection is already configured. Otherwise, it resolves existing values from the active MCP config, application `sdk-config.json`, and environment files; asks once for every missing non-secret value; and writes chat-provided values to every applicable file. It may pause for an environment-sourced Pega MCP client secret (Cursor only) or an MCP reconnect. After the user retries, rerun the gate before executing any data source.
|
|
61
61
|
|
|
62
62
|
### 0.5.1 — Resolve the portal
|
|
63
63
|
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
ai-description: "Generate Pega components styled to match a customer's existing application — given a component list and a Design Profile, produces a
|
|
2
|
+
ai-description: "Generate Pega components styled to match a customer's existing application — given a component list and a Design Profile, produces a generated components folder (location chosen by the user during analysis) with implementations that satisfy the Pega behavioral contract while rendering with the customer's design system, tokens, and styling approach, and reading like their own code"
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
## Step 0 — Resolve missing information
|
|
@@ -7,8 +7,8 @@ ai-description: "Generate Pega components styled to match a customer's existing
|
|
|
7
7
|
Read the user's message carefully. Extract:
|
|
8
8
|
|
|
9
9
|
- **Component list** — the Pega component names to generate (e.g., `TextInput`, `Dropdown`, `DefaultForm`, `TwoColumn`, `ToDo`)
|
|
10
|
-
- **Design Profile location** —
|
|
11
|
-
- **Output path** —
|
|
10
|
+
- **Design Profile location** — always `docs/design-profile.md` at the project root. This location is fixed and never moves with the output path
|
|
11
|
+
- **Output path** — read the **Output Path** field from Section 1 of the Design Profile and use it verbatim as `{output_path}`. Never re-ask for it and never fall back to a hardcoded default — it was already resolved once, with the user, during analysis
|
|
12
12
|
|
|
13
13
|
The **component list** is required. If it is not provided and cannot be inferred from prior conversation context, stop and ask the user.
|
|
14
14
|
|
|
@@ -77,7 +77,7 @@ After every name is resolved, group the canonical names by type so you can read
|
|
|
77
77
|
|
|
78
78
|
Read the following **once** before the generation loop:
|
|
79
79
|
|
|
80
|
-
1. **The Design Profile** — read the full
|
|
80
|
+
1. **The Design Profile** — read the full `docs/design-profile.md`. Its design tokens, styling convention, and validation display convention are authoritative and must be replicated. Its component patterns (input interface, state management, event handling) and file conventions describe the customer's own code — read them for context, but generated components follow the Pega contract and Pega-owned paths instead.
|
|
81
81
|
|
|
82
82
|
2. **General type-level skills** — for each component type present in the grouped list, read the corresponding general skill:
|
|
83
83
|
|
|
@@ -161,17 +161,16 @@ Create the component implementation that satisfies **both**:
|
|
|
161
161
|
|
|
162
162
|
State, events, validation wiring, and prop contracts are deliberately absent from that list — they come from the Pega behavioral contract above, no matter how the customer writes their own forms. A customer whose own screens use a form library does not change how a generated component holds a value or commits it.
|
|
163
163
|
|
|
164
|
-
**Exception — the
|
|
164
|
+
**Exception — the layout beneath `{output_path}` is not the customer's to choose.** The folder the user resolved during analysis is a generated, Pega-owned tree that the customer never authors in, so what goes underneath it is fixed rather than inferred from the Design Profile. Write the component to:
|
|
165
165
|
|
|
166
166
|
```
|
|
167
|
-
{output_path}/{
|
|
167
|
+
{output_path}/{ComponentName}/{ComponentName}.{ext}
|
|
168
168
|
```
|
|
169
169
|
|
|
170
|
-
- `{
|
|
171
|
-
- `{ComponentName}` is the canonical Pega component name resolved in Step 1, verbatim, for both the folder and the implementation file, whatever the customer's naming style is. `Checkbox` produces `Checkbox/Checkbox.*`, never `checkbox/CheckboxField.*`; `Date` produces `Date/Date.*`, never `date/DateField.*`.
|
|
170
|
+
- `{ComponentName}` is the canonical Pega component name resolved in Step 1, verbatim, for both the folder and the implementation file, whatever the customer's naming style is. `Checkbox` produces `Checkbox/Checkbox.*`, never `checkbox/CheckboxField.*`; `Date` produces `Date/Date.*`, never `date/DateField.*`. Components are never grouped into a further `field`/`template`/`widget`/`designSystemExtension`/`infra` subfolder — every component's own folder sits directly under `{output_path}`.
|
|
172
171
|
- `{ext}` follows the customer's framework, not their file-naming style.
|
|
173
172
|
|
|
174
|
-
Deterministic paths are what let tooling
|
|
173
|
+
Deterministic paths are what let tooling and regeneration find components again. Customer conventions govern the _contents_ of these files, not their location or name. If the customer's repo lints file names, exclude `{output_path}` from that rule rather than bending the paths.
|
|
175
174
|
|
|
176
175
|
### 4d. Register the component
|
|
177
176
|
|
|
@@ -277,7 +276,7 @@ Read the generated registry file and confirm:
|
|
|
277
276
|
Verify that every import in the generated files resolves to either:
|
|
278
277
|
|
|
279
278
|
- A package present in the customer's dependency manifest
|
|
280
|
-
- A file within the generated
|
|
279
|
+
- A file within the generated components folder (`{output_path}`)
|
|
281
280
|
- The Pega SDK packages (added in integration wiring)
|
|
282
281
|
|
|
283
282
|
If any import references a package not in the project, either:
|
|
@@ -304,7 +303,7 @@ Whenever `Requested Name` and `Resolved As` differ, say so in your reply as well
|
|
|
304
303
|
|
|
305
304
|
1. **Never invent UI primitives** — only use components available in the customer's UI library or their custom component set
|
|
306
305
|
2. **Never skip behavioral requirements** — every item in the skill file's contract must be implemented, even if the customer's equivalent doesn't natively support it (add the behavior manually)
|
|
307
|
-
3. **Never break existing code** — the generated
|
|
306
|
+
3. **Never break existing code** — the generated components folder (`{output_path}`) is additive; never modify the customer's existing components. This prompt does not wire the integration or verify it — those are separate steps, and they are the only ones permitted to edit the customer's files, confined to the seams their skills enumerate
|
|
308
307
|
4. **Never hardcode design tokens** — always reference the customer's token system (variables, constants, theme values)
|
|
309
308
|
5. **Respect the customer's code conventions** — the contents of generated files should look like the customer wrote them
|
|
310
309
|
6. **One folder per component** — each component gets its own folder named after its canonical Pega name; paths are Pega's, contents are the customer's
|
|
@@ -4,51 +4,104 @@ ai-description: Ensure the Pega server connection (MCP config + sdk-config.json)
|
|
|
4
4
|
|
|
5
5
|
# Pega Server Connection Gate
|
|
6
6
|
|
|
7
|
-
Run this **before** the first Pega data source is executed in a chat session. It
|
|
7
|
+
Run this **before** the first Pega data source is executed in a chat session. It applies to both full-portal and embedded workflows. It resolves connection values from the project's existing configuration, asks once for everything still missing, and synchronizes the active MCP config and browser-served `sdk-config.json`.
|
|
8
8
|
|
|
9
|
-
## 1. Locate the
|
|
9
|
+
## 1. Locate the active configuration files
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
### 1.1 MCP config
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
Find the file this session's AI tool reads its Pega MCP server list from. Do not assume a fixed name or ask the user which file to edit. Search the project for a server entry whose key starts with `pega-` and whose `url` contains `/api/service/v1/mcp/`.
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
Classify the active MCP entry by its shape:
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
- **Cursor-style authenticated MCP** — the entry contains `auth.clientId` and `auth.clientSecret`. Both fields are required for this MCP connection.
|
|
18
|
+
- **URL-only MCP** — the entry has no auth fields, as in Copilot and Claude Code. Do not require, search for, warn about, or mention a client secret for this entry.
|
|
18
19
|
|
|
19
|
-
|
|
20
|
+
### 1.2 Browser-served SDK config
|
|
20
21
|
|
|
21
|
-
|
|
22
|
+
Find the `sdk-config.json` the application actually serves to the browser. Do not automatically choose a same-named file at the project root:
|
|
22
23
|
|
|
23
|
-
-
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
- MCP rule name
|
|
27
|
-
- MCP rule instance key
|
|
28
|
-
- **Client secret — only if the MCP config's server entry has an `auth` block containing a `clientSecret` field.** Some MCP configurations authenticate this way and some do not; let the file's own structure decide whether to ask, rather than deciding by which AI tool is running. If there is no `auth` block, do not ask for a client secret at all.
|
|
24
|
+
- For an embedded project, identify the framework's served static directory (for example `public/`, `static/`, or another directory established by its build configuration) and use the `sdk-config.json` there.
|
|
25
|
+
- For a full-portal project, use its scaffolded application `sdk-config.json`.
|
|
26
|
+
- If more than one copy exists, determine which one the application serves. Report other copies as potentially stale and do not update them.
|
|
29
27
|
|
|
30
|
-
|
|
28
|
+
### 1.3 Environment files
|
|
31
29
|
|
|
32
|
-
|
|
30
|
+
Environment files are commonly excluded by `.gitignore`, so do not rely on an ordinary recursive file search or glob to discover them. First enumerate the project-root directory, including dotfiles, then read every root entry named `.env` or beginning with `.env.` directly by its exact path. If directory enumeration is unavailable, search with ignored files explicitly included. A zero-result ignore-aware search is not evidence that no environment files exist.
|
|
33
31
|
|
|
34
|
-
|
|
32
|
+
Read project-root environment files such as `.env`, `.env.local`, `.env.development`, `.env.production`, and other `.env.*` variants. Never print a secret value.
|
|
35
33
|
|
|
36
|
-
|
|
37
|
-
- `{AppAlias}` → application alias
|
|
38
|
-
- `{MCPRuleName}` → MCP rule name (in both the server key and the URL path)
|
|
39
|
-
- `{MCPRuleInsKey}` → MCP rule instance key
|
|
40
|
-
- `{ClientId}` → client ID, if the entry has an `auth` block
|
|
41
|
-
- `{ClientSecret}` → client secret, if the `auth` block has that field
|
|
34
|
+
## 2. Build the connection inventory
|
|
42
35
|
|
|
43
|
-
|
|
36
|
+
Resolve each field independently from every applicable source. A value is unresolved when it is blank or still contains its scaffold marker.
|
|
44
37
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
38
|
+
| Field | Allowed sources | Destinations |
|
|
39
|
+
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
|
|
40
|
+
| Pega server URL | `serverConfig.infinityRestServerUrl`, the MCP URL, or a matching environment key | SDK config and MCP URL |
|
|
41
|
+
| Application alias | `serverConfig.appAlias`, the MCP URL, or a matching environment key | SDK config and MCP URL |
|
|
42
|
+
| MCP rule name | The `pega-*` MCP server key or a matching environment key | MCP server key only |
|
|
43
|
+
| MCP rule instance key | The MCP URL segment after `/api/service/v1/mcp/` or a matching environment key | MCP URL |
|
|
44
|
+
| OAuth client ID | `authConfig.mashupClientId`, `authConfig.portalClientId`, MCP `auth.clientId` when present, or a matching environment key | Both SDK client-ID fields and MCP `auth.clientId` when present |
|
|
45
|
+
| Pega MCP client secret | A private environment key only, and only when the MCP entry contains `auth.clientSecret` | MCP `auth.clientSecret` only |
|
|
49
46
|
|
|
50
|
-
|
|
47
|
+
The five non-secret fields are required for every tool. The client ID is a public OAuth identifier and may be supplied in chat. A client secret is required only by a Cursor-style authenticated MCP entry; it is not required for the browser SDK or a URL-only Copilot/Claude Code MCP entry.
|
|
51
48
|
|
|
52
|
-
|
|
49
|
+
For non-secret environment values, recognize clear semantic keys ending in `INFINITY_URL`, `SERVER_URL`, `APP_ALIAS`, `MCP_RULE_NAME`, `MCP_RULE_INS_KEY`, `MCP_RULE_INSTANCE_KEY`, or `CLIENT_ID`, including project conventions such as `PEGA_`, `VITE_`, `NEXT_PUBLIC_`, `REACT_APP_`, and `EXPO_PUBLIC_`.
|
|
53
50
|
|
|
54
|
-
|
|
51
|
+
For a client secret, accept only a private key such as `PEGA_CLIENT_SECRET` or `CLIENT_SECRET`. Reject browser-exposed names beginning with `VITE_`, `NEXT_PUBLIC_`, `REACT_APP_`, or `EXPO_PUBLIC_`. Never infer a value from an unrelated key merely because it is the only candidate.
|
|
52
|
+
|
|
53
|
+
Record each field's source and status: configured, missing, or conflicting. For a secret, record presence and source only, never its value.
|
|
54
|
+
|
|
55
|
+
## 3. Resolve conflicts before writing
|
|
56
|
+
|
|
57
|
+
If allowed sources contain different real values for the same non-secret field, show the field and each source/value pair and ask the user which source is authoritative. Do not silently choose or overwrite.
|
|
58
|
+
|
|
59
|
+
If private environment files contain different client-secret values for a Cursor-style MCP entry, state that the secret sources disagree and name only the files and keys. Ask which environment key is authoritative without exposing either value.
|
|
60
|
+
|
|
61
|
+
Equivalent values across sources are not conflicts; consolidate them without asking.
|
|
62
|
+
|
|
63
|
+
## 4. Ask once for every unresolved value
|
|
64
|
+
|
|
65
|
+
After reading all sources, make the first user interaction complete. Show a status table for every applicable field, using only **configured**, **missing**, or **conflicting**. For the client secret, show presence only.
|
|
66
|
+
|
|
67
|
+
In that same response:
|
|
68
|
+
|
|
69
|
+
1. Ask for every missing or conflict-resolved **non-secret** value as one batch. The user may provide these values directly in chat.
|
|
70
|
+
2. Explain that the user may instead edit any allowed source and say when it is ready. Name the exact destinations:
|
|
71
|
+
- Environment: matching semantic keys for any non-secret field.
|
|
72
|
+
- Active `sdk-config.json`: `serverConfig.infinityRestServerUrl`, `serverConfig.appAlias`, `authConfig.mashupClientId`, and `authConfig.portalClientId`.
|
|
73
|
+
- MCP config: `{InfinityURL}` and `{AppAlias}` in the URL, `{MCPRuleName}` in the server key, `{MCPRuleInsKey}` in the URL, and `auth.clientId` when that field exists.
|
|
74
|
+
3. If and only if the active MCP entry contains `auth.clientSecret` and no valid private environment value exists, explain in this first response that the **Pega MCP client secret** is missing. Tell the user to add `PEGA_CLIENT_SECRET` or another private `CLIENT_SECRET`-style key to a project-root environment file and confirm when ready. Never ask them to paste it into chat, put it in `sdk-config.json`, use a browser-exposed env key, or enter it directly into the MCP JSON.
|
|
75
|
+
|
|
76
|
+
Do not stop after reporting a missing Cursor secret without also asking for every missing non-secret value. On every reply or retry, re-read all configuration sources and ask again only for fields that remain unresolved.
|
|
77
|
+
|
|
78
|
+
## 5. Synchronize resolved values
|
|
79
|
+
|
|
80
|
+
Once all five non-secret fields are resolved — and, for a Cursor-style MCP entry, a private environment-sourced secret is resolved — update the active files while preserving unrelated fields.
|
|
81
|
+
|
|
82
|
+
**MCP config:**
|
|
83
|
+
|
|
84
|
+
- Replace `{InfinityURL}` with the server URL.
|
|
85
|
+
- Replace `{AppAlias}` with the application alias.
|
|
86
|
+
- Rename the `pega-{MCPRuleName}` server key with the real MCP rule name. The rule name belongs in the server key, not the endpoint URL.
|
|
87
|
+
- Replace `{MCPRuleInsKey}` with the MCP rule instance key.
|
|
88
|
+
- When `auth.clientId` exists, write the resolved client ID.
|
|
89
|
+
- When `auth.clientSecret` exists, write the private environment-sourced secret without displaying it.
|
|
90
|
+
- Never add an auth block to a URL-only MCP entry.
|
|
91
|
+
|
|
92
|
+
**Active browser-served `sdk-config.json`:**
|
|
93
|
+
|
|
94
|
+
- Write the server URL to `serverConfig.infinityRestServerUrl`.
|
|
95
|
+
- Write the application alias to `serverConfig.appAlias`.
|
|
96
|
+
- Write the client ID to both `authConfig.mashupClientId` and `authConfig.portalClientId`.
|
|
97
|
+
- Do not create new fields or change unrelated values.
|
|
98
|
+
|
|
99
|
+
Never write a client secret into `sdk-config.json`, including `authConfig.portalClientSecret`. This file is served to the browser and is publicly readable. The user's browser-runtime OAuth grant configuration remains their choice; this gate only ensures the required public client ID is present.
|
|
100
|
+
|
|
101
|
+
After writing, re-read both active files and repeat the inventory check. Continue only when all applicable markers are gone, the five non-secret values are non-empty and consistent, and a Cursor-style `auth.clientSecret` was populated from a private environment value. A URL-only MCP entry is complete without any client secret.
|
|
102
|
+
|
|
103
|
+
## 6. Continue or reconnect
|
|
104
|
+
|
|
105
|
+
- If the MCP config changed, tell the user it must be reloaded or reconnected before a Pega data source can run, then stop. Ask them to retry the original request; the invoking workflow must rerun this gate first. If MCP tools were started or attached after the conversation began and are not bound to this session, tell the user to start a new chat session.
|
|
106
|
+
- If only `sdk-config.json` changed and the MCP connection is already available to the conversation, continue the invoking workflow without requiring an unnecessary MCP reconnect.
|
|
107
|
+
- If neither file needed changes, continue immediately.
|
package/templates/react-sdk-reference/.ai-common/skills/embedded-flow/analyze-customer-repo.md
CHANGED
|
@@ -28,6 +28,15 @@ When Pega case flows are embedded into a customer's existing application, the ge
|
|
|
28
28
|
|
|
29
29
|
## Steps
|
|
30
30
|
|
|
31
|
+
### Step 0 — Resolve the output path
|
|
32
|
+
|
|
33
|
+
Every downstream skill and prompt writes generated components to one location: `{output_path}`. Resolve it once, here, before anything else runs. This is separate from the Design Profile document itself, which always lives at the fixed `docs/design-profile.md` and never moves with `{output_path}`.
|
|
34
|
+
|
|
35
|
+
1. **Check for an existing profile first.** Look for `docs/design-profile.md` at the project root — this is its one fixed location, independent of `{output_path}`. If it exists, read its **Output Path** field (Section 1) and reuse that value as `{output_path}` — skip the rest of this step entirely. Do not ask the user again.
|
|
36
|
+
2. **Otherwise, ask.** Ask the user where in their own project the generated Pega components should live. Suggest `pega-components/` at the project root as the default/recommended answer, but accept any path they type instead.
|
|
37
|
+
3. **Validate the answer stays inside the project.** Reject an absolute path outside the project, any `..` traversal segment, or anything else that would resolve outside the project root — re-ask when this happens rather than writing outside the repo.
|
|
38
|
+
4. **Record the confirmed path** as `{output_path}`. It is written into the Design Profile in Step 6 below, and every other embedded-flow skill/prompt reads it from there instead of asking again or assuming a fixed name.
|
|
39
|
+
|
|
31
40
|
### Step 1 — Identify project fundamentals
|
|
32
41
|
|
|
33
42
|
Read the project's dependency manifest (the file that lists packages and their versions). From it, determine:
|
|
@@ -105,7 +114,7 @@ This is what makes it possible to offer the user real choices in their own vocab
|
|
|
105
114
|
|
|
106
115
|
Produce a structured markdown document with the following sections. Use heading levels for organization and bullet lists for values. Do not include source code — describe patterns in prose and reference file paths for the AI to read during generation.
|
|
107
116
|
|
|
108
|
-
**Section 1: Project Fundamentals** — list the framework name and version, language and configuration, UI library name and version (or "Custom"), styling approach, form handling library or pattern, and module system.
|
|
117
|
+
**Section 1: Project Fundamentals** — start with the **Output Path** resolved in Step 0, then list the framework name and version, language and configuration, UI library name and version (or "Custom"), styling approach, form handling library or pattern, and module system.
|
|
109
118
|
|
|
110
119
|
**Section 2: Design Tokens** — organize by sub-sections: Colors (primary, secondary, accent, error, warning, success, background, text, border with their semantic names and values), Spacing (scale), Typography (font families, sizes, weights), Borders and Radii (values), Shadows (elevation values), Breakpoints (if defined).
|
|
111
120
|
|
|
@@ -119,7 +128,7 @@ Produce a structured markdown document with the following sections. Use heading
|
|
|
119
128
|
|
|
120
129
|
**Section 7: Navigation and Surfaces** — list the routing approach and how navigation is triggered, the overlay primitives the project uses and where they come from, the layout shell that wraps a routed page, and a table of existing task entry points giving each control's visible label, its file, and what it does today. The wiring workflow reads this section to decide where the embedded flow renders.
|
|
121
130
|
|
|
122
|
-
Save this document to `
|
|
131
|
+
Save this document to `docs/design-profile.md` in the customer's project, creating the `docs/` folder at the project root first if it does not already exist. This location is fixed — it does not move with `{output_path}`.
|
|
123
132
|
|
|
124
133
|
---
|
|
125
134
|
|
|
@@ -6,7 +6,7 @@ Guide the wiring of generated Pega components into a customer's existing applica
|
|
|
6
6
|
|
|
7
7
|
## Purpose
|
|
8
8
|
|
|
9
|
-
After the
|
|
9
|
+
After the generated components folder (its location is resolved during analysis and recorded in the Design Profile) has been generated (via the component generation prompt), this skill describes the steps to integrate the Pega SDK into the customer's application — connecting authentication, bootstrapping the runtime, launching case flows on user action, and rendering the flow within the application's layout.
|
|
10
10
|
|
|
11
11
|
**Step 0 is the exception.** It is a gate, not an integration step, and it runs _before_ generation — see its own heading for why.
|
|
12
12
|
|
|
@@ -14,7 +14,7 @@ After the `pega-components/` folder has been generated (via the component genera
|
|
|
14
14
|
|
|
15
15
|
## Prerequisites
|
|
16
16
|
|
|
17
|
-
- The
|
|
17
|
+
- The generated components folder (its location is resolved during analysis and recorded in the Design Profile) exists with generated components and a registry file named `component-map` (the extension follows the customer's framework) — required from **Step 1 onward**. Step 0 runs before generation and needs only the customer's codebase and the Design Profile
|
|
18
18
|
- The customer has a Pega Infinity environment with:
|
|
19
19
|
- An OAuth 2.0 client configured for the application
|
|
20
20
|
- A case type to embed (e.g., a service request, onboarding flow)
|
|
@@ -155,7 +155,7 @@ Add the following Pega packages to the project's dependency manifest:
|
|
|
155
155
|
| The Pega SDK types package | Shared type definitions and interfaces |
|
|
156
156
|
| The Pega ConstellationJS core package | Runtime engine that provides the PCore global |
|
|
157
157
|
|
|
158
|
-
These are the only external additions. The generated
|
|
158
|
+
These are the only external additions. The generated components use the customer's existing UI library — no additional design system packages are needed.
|
|
159
159
|
|
|
160
160
|
If SDK packages were provided as `.tgz` files (interim distribution), they should already be in the project root with `file:` references in the dependency manifest. Run the project's package install command to link them.
|
|
161
161
|
|
|
@@ -295,7 +295,7 @@ The module-scoped singleton avoids this entirely because it is immune to compone
|
|
|
295
295
|
|
|
296
296
|
1. **Authenticate** — use the SDK auth client to perform login (OAuth redirect or silent renewal)
|
|
297
297
|
2. **Bootstrap in embedded/mashup mode** — initialize the SDK runtime in mashup mode (not full portal), capturing the render context returned by bootstrap
|
|
298
|
-
3. **Create the component registry** — instantiate the SDK's component registry and register all components exported by the generated `
|
|
298
|
+
3. **Create the component registry** — instantiate the SDK's component registry and register all components exported by the generated components folder's `component-map` registry file
|
|
299
299
|
4. **Register the component creator** — tell the SDK runtime to use the registered components for rendering
|
|
300
300
|
|
|
301
301
|
This module should expose:
|
|
@@ -433,7 +433,7 @@ Do not report the integration as complete on static checks alone.
|
|
|
433
433
|
│ │ │ │ │ │
|
|
434
434
|
│ │ │ SDK Bridge Component │ │ │
|
|
435
435
|
│ │ │ ↓ resolves from registry │ │ │
|
|
436
|
-
│ │ │
|
|
436
|
+
│ │ │ generated components folder (generated, customer-styled) │ │ │
|
|
437
437
|
│ │ │ ↓ wired to │ │ │
|
|
438
438
|
│ │ │ PConnect (Pega runtime state + actions) │ │ │
|
|
439
439
|
│ │ └─────────────────────────────────────────────────┘ │ │
|
|
@@ -470,7 +470,7 @@ Common integration failures and their resolutions. These are ordered by how they
|
|
|
470
470
|
|
|
471
471
|
## Notes
|
|
472
472
|
|
|
473
|
-
- The generated
|
|
473
|
+
- The generated components folder (its location is resolved during analysis and recorded in the Design Profile) has zero dependencies beyond the customer's existing UI library and the Pega SDK packages. No additional design system installation is needed.
|
|
474
474
|
- The bootstrap module should handle token refresh/silent renewal automatically via the SDK auth client.
|
|
475
475
|
- If the customer's app already has authentication, coordinate with their auth flow — the SDK auth client can share tokens if the same OAuth provider is used.
|
|
476
476
|
- The Pega rendering container can be a modal, a sidebar, an inline section, or a full page. Which one is not a matter of taste — it is resolved in Step 0.2 from what the user asked for or from what their application already does.
|