@pega/sdk 0.0.13 → 0.0.15

package/README.md

@@ -8,12 +8,21 @@ building right away.
 ## For AI Coding Agents
 
 Recognize these as requests to run this CLI, whether the folder is empty or already
-has a project in it:
-
-- "Scaffold a new Pega app / project using `@pega/sdk`" → run in an **empty folder**.
-- "Scaffold `@pega/sdk` / add Pega embedded flow into this repo" (or similar,
-  said while working inside an existing host application) → run in that
-  **existing project's folder**.
+has a project in it. Users rarely use these words — judge by what they want, not
+by how they say it:
+
+- **They want a Pega form or workflow inside the app they already have** → run in
+  that **existing project's folder**. For example: "Scaffold `@pega/sdk` / add Pega
+  embedded flow into this repo", "add the service request form to my app when
+  someone clicks Apply", "show a Pega form inside my page", "let customers raise a
+  case from our website".
+- **They want a new Pega app or portal** → run in an **empty folder**. For example:
+  "Scaffold a new Pega app / project using `@pega/sdk`", "start a new Pega app with
+  Chakra UI", "build me a Pega portal".
+
+The examples are illustrations, not a complete list. Ask the user only when the
+request is genuinely unclear — for example, they say "my app" but the folder is
+empty.
 
 In both cases, run `npx --yes @pega/sdk init` non-interactively — see
 [Non-Interactive / Scripted Usage](#non-interactive--scripted-usage) below for the
@@ -36,6 +45,12 @@ about or guess:
 | `--mode` (auto-detected from whether `package.json` exists in the cwd)                                              | none — these are all optional and not needed to scaffold |
 | `--ai-tool` (set it to yourself: GitHub Copilot → `copilot`, Cursor → `cursor`, Claude Code → `claude-code`)        |                                                          |
 | `--framework`, `--name`, `--templates`, `--categories` (infer from the request, or ask only if genuinely ambiguous) |                                                          |
+| `--conflict-policy` (embedded mode only — see below)                                                                |                                                          |
+
+`--conflict-policy` applies only in embedded mode and is ignored in new-project
+mode. Leave it at `merge` (the default): it keeps the host's existing files, adds
+Pega content inside marked blocks, and fills in missing JSON keys. Pass `override`
+only when the user explicitly asks to replace their existing files.
 
 Server connection details (Pega server URL, app alias, OAuth client ID, MCP rule
 name/instance key) are never asked at scaffold time, in either mode — the scaffold
@@ -44,6 +59,31 @@ placeholder markers. An AI coding assistant gathers these from the user in chat
 and fills both files in automatically the first time a workflow needs them (see
 [Configure Your Pega Server](#configure-your-pega-server)).
 
+### After the command finishes
+
+When `--ai-tool` is set, the CLI prints the project folder, the agent to continue
+with, and its files. Files written during your current turn are not in your context
+yet, so do not carry on from memory:
+
+| Mode        | Agent                     | Continue when                                                                                                  |
+| ----------- | ------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Embedded    | **Embedded Flow Expert**  | Always                                                                                                         |
+| New project | **Implementation Expert** | Only when the user asked for more than a new project (e.g. "…with Chakra UI"); otherwise give plain next steps |
+
+| AI tool     | Project instructions              | Agent file                             | What to do                                                                                                                                                         |
+| ----------- | --------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Copilot     | `.github/copilot-instructions.md` | `.github/agents/<agent>.agent.md`      | Stop. Tell the user to choose the agent in the agent menu and say "continue"                                                                                       |
+| Cursor      | `.cursor/rules/pega-sdk.mdrules`  | `.cursor/rules/agents/<agent>.mdrules` | Stop. Tell the user to `@`-mention the agent (e.g. `@embedded-flow-expert`) in chat                                                                                |
+| Claude Code | `AGENTS.md`                       | `.claude/agents/<agent>.md`            | Read both files, then continue the user's original request in this chat. Suggest a new session for later requests, so the project instructions load from the start |
+
+- **Say it in plain words**, for example: "Setup is done. To continue, choose
+  **Embedded Flow Expert** in the agent menu and say 'continue'." For Copilot and
+  Cursor, repeat the user's original request so they can paste it.
+- **New project:** the AI tools find these files only at the top of the open
+  folder, so the user must open the printed project folder first, in every tool.
+- **No agent printed** (a framework without AI files, or `--ai-tool none`): give
+  plain next steps only.
+
 ## Requirements
 
 - **Node.js** 20 or later

package/dist/index.js

@@ -4,6 +4,7 @@
 import * as p from "@clack/prompts";
 import pc from "picocolors";
 import path4 from "path";
+import fs4 from "fs";
 import { createRequire } from "module";
 
 // src/scaffold.ts
@@ -206,6 +207,10 @@ var DSE_COMPONENTS = [
     importName: "AlertBanner",
     importPath: "./designSystemExtension/AlertBanner"
   },
+  {
+    importName: "AssignmentHeader",
+    importPath: "./designSystemExtension/AssignmentHeader"
+  },
   { importName: "Banner", importPath: "./designSystemExtension/Banner" },
   {
     importName: "CaseSummaryFields",
@@ -233,6 +238,7 @@ var DSE_COMPONENTS = [
     importName: "RichTextEditor",
     importPath: "./designSystemExtension/RichTextEditor"
   },
+  { importName: "Toast", importPath: "./designSystemExtension/Toast" },
   {
     importName: "WssQuickCreate",
     importPath: "./designSystemExtension/WssQuickCreate"
@@ -762,6 +768,15 @@ var AI_GEN_CONFIGS = {
     }
   }
 };
+var GLOBAL_INSTRUCTIONS_PATHS = {
+  copilot: ".github/copilot-instructions.md",
+  cursor: ".cursor/rules/pega-sdk.mdrules",
+  "claude-code": "AGENTS.md"
+};
+function aiAgentFiles(aiTool, agent) {
+  const cfg = AI_GEN_CONFIGS[aiTool];
+  return { agentFile: `${cfg.agentsDir}/${agent}.${cfg.agentExt}`, globalFile: GLOBAL_INSTRUCTIONS_PATHS[aiTool] };
+}
 function parseAiMeta(content) {
   const match = content.match(/^---\n([\s\S]*?)\n---\n\n?/);
   if (!match) return { meta: {}, body: content };
@@ -954,21 +969,21 @@ description: "${description}"
     const body = applyTokens(fs2.readFileSync(globalSrc, "utf-8"), tokens);
     if (aiTool === "copilot") {
       planned.push({
-        destPath: path2.join(targetDir, ".github", "copilot-instructions.md"),
+        destPath: path2.join(targetDir, GLOBAL_INSTRUCTIONS_PATHS.copilot),
         frontmatter: "",
         body,
         kind: "md"
       });
     } else if (aiTool === "cursor") {
       planned.push({
-        destPath: path2.join(targetDir, ".cursor", "rules", "pega-sdk.mdrules"),
+        destPath: path2.join(targetDir, GLOBAL_INSTRUCTIONS_PATHS.cursor),
         frontmatter: "---\ndescription: Core rules for working with Pega SDK components\nalwaysApply: true\n---\n\n",
         body,
         kind: "md"
       });
     } else if (aiTool === "claude-code") {
       planned.push({
-        destPath: path2.join(targetDir, "AGENTS.md"),
+        destPath: path2.join(targetDir, GLOBAL_INSTRUCTIONS_PATHS["claude-code"]),
         frontmatter: "",
         body,
         kind: "md"
@@ -1122,32 +1137,23 @@ async function scaffoldEmbedded(choices, targetDir, onProgress) {
     `Wrote ${planned.length} file(s): ${counts.created} new, ${counts["block-replaced"]} updated, ${counts.appended} merged, ${counts.overwritten} replaced.`
   );
   report("Copying SDK packages\u2026");
-  const tgzFiles = fs2.readdirSync(sampleDir).filter((f) => f.endsWith(".tgz"));
-  for (const tgz of tgzFiles) {
-    const src = path2.join(sampleDir, tgz);
-    const dest = path2.join(targetDir, tgz);
-    fs2.copyFileSync(src, dest);
+  const samplePkgJson = JSON.parse(fs2.readFileSync(path2.join(sampleDir, "package.json"), "utf-8"));
+  const pegaDependencies = {};
+  for (const pkgName of ["@pega/auth", "@pega/constellationjs", "@pega/sdk-react", "@pega/sdk-types"]) {
+    const spec = samplePkgJson.dependencies?.[pkgName];
+    if (!spec) continue;
+    pegaDependencies[pkgName] = spec;
+    if (spec.startsWith("file:")) {
+      const tgz = spec.slice("file:".length);
+      fs2.copyFileSync(path2.join(sampleDir, tgz), path2.join(targetDir, tgz));
+    }
   }
   report("Adding SDK dependencies\u2026");
   const pkgJsonPath = path2.join(targetDir, "package.json");
   if (fs2.existsSync(pkgJsonPath)) {
     const pkgJson = JSON.parse(fs2.readFileSync(pkgJsonPath, "utf-8"));
     if (!pkgJson.dependencies) pkgJson.dependencies = {};
-    const TGZ_PACKAGE_MAP = {
-      "pega-auth": "@pega/auth",
-      "pega-constellationjs": "@pega/constellationjs",
-      "pega-sdk-react": "@pega/sdk-react",
-      "pega-sdk-types": "@pega/sdk-types"
-    };
-    for (const tgz of tgzFiles) {
-      const match = tgz.match(/^(pega-[\w-]+?)-\d/);
-      if (match) {
-        const pkgName = TGZ_PACKAGE_MAP[match[1]];
-        if (pkgName) {
-          pkgJson.dependencies[pkgName] = `file:${tgz}`;
-        }
-      }
-    }
+    Object.assign(pkgJson.dependencies, pegaDependencies);
     fs2.writeFileSync(pkgJsonPath, JSON.stringify(pkgJson, null, 2) + "\n");
   }
   report("Creating SDK configuration\u2026");
@@ -1254,7 +1260,17 @@ do not need to pass --mode.
 about. GitHub Copilot -> copilot, Cursor -> cursor, Claude Code -> claude-code.
 Always pass it: it decides which agent config files get written, and a repo can
 contain another assistant's config left behind by someone else.
-`.trim();
+
+Users often ask in plain words ("add the service request form to my app when
+someone clicks Apply", "start a new Pega app") \u2014 judge by intent, not wording.
+
+When it finishes, the CLI prints the agent to continue with and its files.
+  Copilot / Cursor: stop. Tell the user, in plain words, to switch to that agent
+    (Copilot: pick it in the agent menu; Cursor: @-mention it in chat), then
+    repeat their original request so they can paste it.
+  Claude Code: read the printed instructions and agent files, then continue the
+    user's original request in this chat.
+New project: the user must open the printed project folder first.`.trim();
 var HELP_TEXT = `
 Usage: npx --yes @pega/sdk init [flags]
 
@@ -1423,6 +1439,14 @@ function resolveNonInteractiveEmbeddedChoices(args, cwd) {
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version: sdkVersion } = require2("../package.json");
+function printAgentFiles(projectDir, aiTool, agent, agentName) {
+  if (!aiTool) return;
+  const { agentFile, globalFile } = aiAgentFiles(aiTool, agent);
+  if (!fs4.existsSync(path4.join(projectDir, agentFile)) || !fs4.existsSync(path4.join(projectDir, globalFile))) return;
+  console.log(`Project folder: ${projectDir}`);
+  console.log(`Agent: ${agentName} \u2014 ${agentFile}`);
+  console.log(`Project instructions: ${globalFile}`);
+}
 async function runNonInteractive(cwd, flags) {
   try {
     const mode = flags.mode ?? (detectExistingProject(cwd) ? "embedded" : "new");
@@ -1438,11 +1462,13 @@ async function runNonInteractive(cwd, flags) {
       }
       await scaffoldEmbedded(choices, cwd, (message) => console.log(pc.dim(message)));
       console.log(pc.green("Embedded flow ready!"));
+      printAgentFiles(cwd, choices.aiTool, "embedded-flow-expert", "Embedded Flow Expert");
     } else {
       const choices = resolveNonInteractiveUserChoices(flags);
       const targetDir = path4.resolve(cwd, choices.projectName);
       await scaffold(choices, targetDir, (message) => console.log(pc.dim(message)));
       console.log(pc.green("Project scaffolded successfully!"));
+      printAgentFiles(targetDir, choices.aiTool, "implementation-expert", "Implementation Expert");
     }
   } catch (err) {
     console.error(pc.red(err instanceof CliValidationError || err instanceof Error ? err.message : String(err)));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pega/sdk",
-  "version": "0.0.13",
-  "description": "Scaffold a Pega SDK application project",
+  "version": "0.0.15",
+  "description": "CLI to scaffold Pega SDK apps (React, Angular, Web Components) or embed Pega cases and forms into an existing app, with design-matched components and AI agent setup for Copilot, Cursor, and Claude Code",
   "type": "module",
   "bin": {
     "sdk": "./dist/index.js"
@@ -39,7 +39,46 @@
     "sdk",
     "scaffold",
     "cli",
-    "create-app"
+    "create-app",
+    "embed",
+    "embedded",
+    "mashup",
+    "constellation",
+    "pega-infinity",
+    "case",
+    "form",
+    "forms",
+    "workflow",
+    "ui",
+    "components",
+    "design-system",
+    "pega-sdk",
+    "pega-constellation",
+    "constellation-sdk",
+    "pega-mashup",
+    "pega-react-sdk",
+    "pega-angular-sdk",
+    "web-embed",
+    "embed-form",
+    "embed-case",
+    "case-management",
+    "workflow-automation",
+    "low-code",
+    "react",
+    "angular",
+    "web-components",
+    "react-native",
+    "typescript",
+    "vite",
+    "starter",
+    "boilerplate",
+    "template",
+    "ai-agent",
+    "copilot",
+    "cursor",
+    "claude-code",
+    "mcp",
+    "oauth"
   ],
   "license": "Apache-2.0"
 }

package/templates/angular-sdk-reference/extra-webpack.config.cjs

@@ -0,0 +1,23 @@
+'use strict';
+
+const CopyWebpackPlugin = require('copy-webpack-plugin');
+
+// comment this code out, if you have an "ENOENT: no such file or directory" build error and re-build
+// to see the real Angular errors, then uncomment onces fixed
+module.exports = (config) => {
+  config.plugins.push(
+    new CopyWebpackPlugin({
+      patterns: [
+        {
+          from: '../../node_modules/@pega/auth/lib/oauth-client/authDone.html',
+          to: './auth.html',
+        },
+        {
+          from: '../../node_modules/@pega/auth/lib/oauth-client/authDone.js',
+          to: './',
+        },
+      ],
+    }),
+  );
+  return config;
+};

package/templates/angular-sdk-reference/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Pega SDK Angular Reference</title>
+    <base href="/" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <app-root></app-root>
+  </body>
+</html>

package/templates/angular-sdk-reference/src/app/pconnect-renderer.component.ts

@@ -0,0 +1,153 @@
+/**
+ * PConnectRendererComponent — Recursive Angular component that renders
+ * the PConnect c11nEnv tree as a visual fallback display.
+ *
+ * This is the Angular equivalent of React's PConnectComponent + FallbackComponent.
+ * It uses PConnectObservable from sdk-core to subscribe to state changes
+ * and recursively renders the component tree.
+ */
+
+import {
+  Component,
+  Input,
+  OnInit,
+  OnDestroy,
+  NgZone,
+  ChangeDetectorRef,
+} from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { PegaBridgeService } from '@pega/sdk-angular';
+import type { PConnectState, Unsubscribe } from '@pega/sdk-angular';
+
+@Component({
+  selector: 'app-pconnect-renderer',
+  standalone: true,
+  imports: [CommonModule],
+  template: `
+    <div class="node">
+      <div class="node-header">{{ componentName }}</div>
+
+      <pre *ngIf="displayPropsJson" class="node-props">{{
+        displayPropsJson
+      }}</pre>
+
+      <!-- Recursively render children -->
+      <div *ngIf="childEnvs.length > 0" class="node-children">
+        <app-pconnect-renderer
+          *ngFor="let child of childEnvs; trackBy: trackByIndex"
+          [pConnect]="child"
+        ></app-pconnect-renderer>
+      </div>
+    </div>
+  `,
+  styles: [
+    `
+      .node {
+        border: 1px solid #ddd;
+        border-radius: 4px;
+        margin: 4px;
+        padding: 8px;
+        font-size: 13px;
+        font-family: system-ui, sans-serif;
+      }
+      .node-header {
+        background: #f0f4ff;
+        padding: 4px 8px;
+        border-radius: 3px;
+        font-size: 12px;
+        font-weight: 600;
+        color: #1a56db;
+        margin-bottom: 4px;
+      }
+      .node-props {
+        font-size: 11px;
+        color: #555;
+        margin: 4px 0;
+        max-height: 100px;
+        overflow: auto;
+        background: #fafafa;
+        padding: 4px;
+        border-radius: 3px;
+        white-space: pre-wrap;
+      }
+      .node-children {
+        padding-left: 12px;
+      }
+    `,
+  ],
+})
+export class PConnectRendererComponent implements OnInit, OnDestroy {
+  @Input() pConnect!: typeof PConnect;
+
+  componentName = 'Unknown';
+  displayPropsJson = '';
+  childEnvs: Array<typeof PConnect> = [];
+
+  private bridge = new PegaBridgeService();
+  private unsubscribe: Unsubscribe | null = null;
+
+  constructor(
+    private ngZone: NgZone,
+    private cdr: ChangeDetectorRef,
+  ) {}
+
+  ngOnInit(): void {
+    if (!this.pConnect) return;
+
+    // Resolve component name
+    const pc = this.pConnect as any;
+    this.componentName =
+      pc.getComponentName?.() ?? pc.componentName ?? 'Unknown';
+
+    // Create observable for state changes
+    const subscription = this.bridge.observe(this.pConnect).subscribe((state: PConnectState) => {
+      this.ngZone.run(() => {
+        this.applyState(state);
+        this.cdr.markForCheck();
+      });
+    });
+    this.unsubscribe = () => subscription.unsubscribe();
+
+    // Resolve children
+    this.resolveChildren();
+  }
+
+  ngOnDestroy(): void {
+    this.unsubscribe?.();
+  }
+
+  trackByIndex(index: number): number {
+    return index;
+  }
+
+  private applyState(state: PConnectState): void {
+    // Filter out function props and internal props for display
+    const displayProps = Object.fromEntries(
+      Object.entries(state.configProps).filter(
+        ([key, value]) =>
+          typeof value !== 'function' &&
+          !['getPConnect', 'pConnect', 'visibility'].includes(key),
+      ),
+    );
+    const json = JSON.stringify(displayProps, null, 2);
+    this.displayPropsJson = json !== '{}' ? json : '';
+  }
+
+  private resolveChildren(): void {
+    const pc = this.pConnect as any;
+    if (!pc.hasChildren?.()) {
+      this.childEnvs = [];
+      return;
+    }
+
+    const children = pc.getChildren?.() as any[];
+    if (!children) {
+      this.childEnvs = [];
+      return;
+    }
+
+    this.childEnvs = children.map((childEnv: any) => {
+      return childEnv.getPConnect ? childEnv.getPConnect() : childEnv;
+    });
+  }
+}

package/templates/angular-sdk-reference/src/components/component-map.ts

@@ -0,0 +1,90 @@
+/**
+ * Angular sample component map — maps Pega component names to Angular component classes.
+ *
+ * Mirrors the getSampleComponentMap() pattern from @pega/sdk-react.
+ */
+
+import type { Type } from '@angular/core';
+import { registerAngularComponentMap } from '@pega/sdk-angular';
+
+// Infrastructure
+import { RootContainerComponent } from './infra/root-container/root-container.component';
+import { ViewContainerComponent } from './infra/view-container/view-container.component';
+import { FlowContainerComponent } from './infra/flow-container/flow-container.component';
+import { AssignmentComponent } from './infra/assignment/assignment.component';
+import { ViewComponent } from './infra/view/view.component';
+import { ReferenceComponent } from './infra/reference/reference.component';
+import { RegionComponent } from './infra/region/region.component';
+import { CaseViewComponent } from './infra/case-view/case-view.component';
+import { CaseSummaryComponent } from './infra/case-summary/case-summary.component';
+import { StagesComponent } from './infra/stages/stages.component';
+
+// Templates
+import { DefaultFormComponent } from './templates/default-form/default-form.component';
+import { OneColumnComponent } from './templates/one-column/one-column.component';
+import { TwoColumnComponent } from './templates/two-column/two-column.component';
+import { NarrowWideComponent } from './templates/narrow-wide/narrow-wide.component';
+import { WideNarrowComponent } from './templates/wide-narrow/wide-narrow.component';
+
+// Fields
+import { TextInputComponent } from './fields/text-input/text-input.component';
+import { TextAreaComponent } from './fields/text-area/text-area.component';
+import { DropdownComponent } from './fields/dropdown/dropdown.component';
+import { CheckboxComponent } from './fields/checkbox/checkbox.component';
+import { RadioButtonsComponent } from './fields/radio-buttons/radio-buttons.component';
+import { CurrencyComponent } from './fields/currency/currency.component';
+import { DateInputComponent } from './fields/date-input/date-input.component';
+import { EmailComponent } from './fields/email/email.component';
+import { PhoneComponent } from './fields/phone/phone.component';
+import { IntegerComponent } from './fields/integer/integer.component';
+import { URLInputComponent } from './fields/url-input/url-input.component';
+import { AutoCompleteComponent } from './fields/auto-complete/auto-complete.component';
+
+function getSampleAngularComponentMap(): Record<string, Type<unknown>> {
+  return {
+    // Fields
+    TextInput: TextInputComponent,
+    TextArea: TextAreaComponent,
+    Dropdown: DropdownComponent,
+    Checkbox: CheckboxComponent,
+    RadioButtons: RadioButtonsComponent,
+    Currency: CurrencyComponent,
+    Date: DateInputComponent,
+    Email: EmailComponent,
+    Phone: PhoneComponent,
+    Integer: IntegerComponent,
+    URL: URLInputComponent,
+    AutoComplete: AutoCompleteComponent,
+
+    // Templates
+    DefaultForm: DefaultFormComponent,
+    OneColumn: OneColumnComponent,
+    TwoColumn: TwoColumnComponent,
+    NarrowWide: NarrowWideComponent,
+    WideNarrow: WideNarrowComponent,
+
+    // Infrastructure
+    Assignment: AssignmentComponent,
+    RootContainer: RootContainerComponent,
+    ViewContainer: ViewContainerComponent,
+    FlowContainer: FlowContainerComponent,
+    View: ViewComponent,
+    Region: RegionComponent,
+    CaseView: CaseViewComponent,
+    CaseSummary: CaseSummaryComponent,
+    Stages: StagesComponent,
+
+    // Aliases — PCore may use different name variants
+    AppShell: RootContainerComponent,
+    CaseViewContainer: ViewContainerComponent,
+    SubTabs: ViewContainerComponent,
+    DeferLoad: ViewContainerComponent,
+    reference: ReferenceComponent,
+  };
+}
+
+function registerSampleAngularComponents(): void {
+  registerAngularComponentMap(getSampleAngularComponentMap());
+}
+
+export { getSampleAngularComponentMap, registerSampleAngularComponents };