@pega/sdk 0.0.8 → 0.0.10

package/README.md

@@ -5,6 +5,41 @@ fully configured project — build tooling, authentication, runtime bootstrap, a
 optional starter components — so you can connect to your Pega server and start
 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**.
+
+In both cases, run `npx @pega/sdk init` non-interactively — see
+[Non-Interactive / Scripted Usage](#non-interactive--scripted-usage) below for the
+full flag reference. Gather answers conversationally, then invoke one command; do
+not try to drive the interactive prompts through a terminal.
+
+Mode is decided by the folder you run the command in, not something you need to ask
+about or guess:
+
+- **Empty folder (no `package.json`)** → new project / full portal mode. Omit
+  `--mode`; it defaults to `new`.
+- **Folder already contains a project (`package.json` present)** → embedded mode.
+  Omit `--mode`; it defaults to `embedded`. (Pass `--mode` explicitly only to
+  override this auto-detection.)
+
+| Decide yourself (don't ask the user)                                                                                | Ask the user (can't be inferred)                         |
+| ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| `--mode` (auto-detected from whether `package.json` exists in the cwd)                                              | none — these are all optional and not needed to scaffold |
+| `--ai-tool` (you know which tool you are)                                                                           |                                                          |
+| `--framework`, `--name`, `--templates`, `--categories` (infer from the request, or ask only if genuinely ambiguous) |                                                          |
+
+`--server-url` / `--app-alias` / `--client-id` / `--mcp-rule-name` / `--mcp-rule-ins-key`
+are optional, CI-only flags. Do not prompt the user for them at scaffold time —
+they're configured afterward by editing `sdk-config.json` and the generated MCP
+config file directly (see [Configure Your Pega Server](#configure-your-pega-server)).
+
 ## Requirements
 
 - **Node.js** 20 or later
@@ -58,6 +93,29 @@ Running `init` walks you through an interactive setup:
 If you skip starter components in a React project, the scaffold uses a minimal
 dependency manifest for a lighter baseline app.
 
+Server connection details (Pega server URL, app alias, OAuth client ID) and MCP
+rule details are no longer asked interactively — edit `sdk-config.json` and the
+generated MCP config file after scaffolding (see below).
+
+## Non-Interactive / Scripted Usage
+
+Pass any flag to `init` (or `--json`) to scaffold in one shot, with no prompts:
+
+```bash
+# New project
+npx @pega/sdk init --name my-app --framework react --ai-tool copilot --templates false --yes
+
+# Embedded flow, inside an existing project
+npx @pega/sdk init --mode embedded --ai-tool copilot --conflict-policy merge
+
+# Or supply everything via a JSON answers file (values here win over individual flags)
+npx @pega/sdk init --json ./sdk-answers.json
+```
+
+Run `npx @pega/sdk init --help` for the full flag reference. On invalid or
+missing required input, the CLI prints an error to stderr and exits with a
+non-zero code — no hanging prompt.
+
 ## What You Get
 
 The generated project is ready to run and includes:

package/dist/index.js

@@ -3,7 +3,7 @@
 // src/index.ts
 import * as p from "@clack/prompts";
 import pc from "picocolors";
-import path3 from "path";
+import path4 from "path";
 import { createRequire } from "module";
 
 // src/scaffold.ts
@@ -1046,14 +1046,8 @@ function resolveEmbeddedSource() {
   }
   return { sampleDir, aiCommonSrc };
 }
-var SDK_CONFIG_USER_KEYS = [
-  "serverConfig.infinityRestServerUrl",
-  "serverConfig.appAlias",
-  "authConfig.mashupClientId",
-  "authConfig.mashupUserIdentifier",
-  "authConfig.portalClientId"
-];
-var MCP_CONFIG_USER_KEYS = ["url", "clientId"];
+var SDK_CONFIG_USER_KEYS = [];
+var MCP_CONFIG_USER_KEYS = [];
 var MCP_CONFIG_FILES = {
   copilot: { source: "copilot.mcp.json", dest: path2.join(".vscode", "mcp.json") },
   cursor: { source: "cursor.mcp.json", dest: path2.join(".cursor", "mcp.json") },
@@ -1065,11 +1059,10 @@ function resolveMcpConfig(aiCommonSrc, choices) {
   if (!fs2.existsSync(srcPath)) {
     throw new Error(`MCP config template not found at ${srcPath}. Ensure the template source is available.`);
   }
-  const tokens = {
-    "{InfinityURL}": choices.serverUrl,
-    "{AppAlias}": choices.appAlias,
-    "{ClientId}": choices.clientId
-  };
+  const tokens = {};
+  if (choices.serverUrl) tokens["{InfinityURL}"] = choices.serverUrl;
+  if (choices.appAlias) tokens["{AppAlias}"] = choices.appAlias;
+  if (choices.clientId) tokens["{ClientId}"] = choices.clientId;
   if (choices.mcpRuleName) tokens["{MCPRuleName}"] = choices.mcpRuleName;
   if (choices.mcpRuleInsKey) tokens["{MCPRuleInsKey}"] = choices.mcpRuleInsKey;
   const content = applyTokens(fs2.readFileSync(srcPath, "utf-8"), tokens);
@@ -1085,8 +1078,8 @@ function ensureGitignoreEntry(targetDir, entry) {
 function buildSdkConfig(choices) {
   return {
     serverConfig: {
-      infinityRestServerUrl: choices.serverUrl,
-      appAlias: choices.appAlias,
+      infinityRestServerUrl: choices.serverUrl ?? "",
+      appAlias: choices.appAlias ?? "",
       sdkContentServerUrl: "",
       appPortal: "",
       appMashupCaseType: "",
@@ -1101,10 +1094,10 @@ function buildSdkConfig(choices) {
     },
     authConfig: {
       authService: "pega",
-      mashupClientId: choices.clientId,
-      mashupUserIdentifier: choices.userIdentifier,
+      mashupClientId: choices.clientId ?? "",
+      mashupUserIdentifier: "",
       mashupPassword: "",
-      portalClientId: choices.clientId,
+      portalClientId: choices.clientId ?? "",
       portalClientSecret: "",
       portalGrantType: ""
     }
@@ -1247,22 +1240,250 @@ function copyDir(src, dest) {
   }
 }
 
+// src/cli-args.ts
+import { parseArgs } from "util";
+import fs3 from "fs";
+import path3 from "path";
+var ALL_CATEGORIES = ["fields", "templates", "widgets", "infra", "designSystemExtension"];
+var FRAMEWORKS = ["react", "angular", "web-components", "react-native"];
+var AI_TOOLS = ["copilot", "cursor", "claude-code"];
+var PROJECT_NAME_RE = /^[a-z0-9@][a-z0-9._/-]*$/;
+var CliValidationError = class extends Error {
+};
+var HELP_TEXT = `
+Usage: npx @pega/sdk init [flags]
+
+Run with no flags for the interactive setup. Pass any flag below (or --json)
+to scaffold non-interactively in one shot \u2014 no prompts are shown.
+
+Common:
+  --json <path|->        Answers file (JSON), matching the shapes documented in
+                          README.md. Use "-" to read from stdin. Values here win
+                          over the individual flags below when both are given.
+  --mode <new|embedded>   Override auto-detection of new-project vs embedded.
+  --ai-tool <tool>        copilot | cursor | claude-code (embedded: required; new: also accepts "none")
+  --help                  Show this help.
+
+New project:
+  --name <name>           Project directory name (required).
+  --framework <fw>        react | angular | web-components | react-native (required).
+  --templates <bool>      Include starter components. Default: true.
+  --categories <list>     Comma-separated: fields,templates,widgets,infra,designSystemExtension.
+                          Default: all categories when --templates is true.
+
+Embedded:
+  --conflict-policy <p>   merge | override. Default: merge.
+
+Optional, either mode (CI/scripted use only \u2014 a chat agent should not ask a
+user for these; they're configured post-scaffold by editing sdk-config.json /
+the generated MCP config file):
+  --server-url <url>
+  --app-alias <alias>
+  --client-id <id>
+  --mcp-rule-name <name>
+  --mcp-rule-ins-key <key>
+
+Examples:
+  npx @pega/sdk init --name my-app --framework react --ai-tool copilot --templates false --yes
+  npx @pega/sdk init --mode embedded --ai-tool copilot --conflict-policy merge
+  npx @pega/sdk init --json ./sdk-answers.json
+`.trim();
+function parseCliArgs(argv) {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: argv,
+      options: {
+        help: { type: "boolean" },
+        json: { type: "string" },
+        yes: { type: "boolean" },
+        mode: { type: "string" },
+        name: { type: "string" },
+        framework: { type: "string" },
+        "ai-tool": { type: "string" },
+        "server-url": { type: "string" },
+        "app-alias": { type: "string" },
+        "client-id": { type: "string" },
+        "mcp-rule-name": { type: "string" },
+        "mcp-rule-ins-key": { type: "string" },
+        templates: { type: "string" },
+        categories: { type: "string" },
+        "conflict-policy": { type: "string" }
+      },
+      strict: true,
+      allowPositionals: true
+    }));
+  } catch (err) {
+    throw new CliValidationError(err instanceof Error ? err.message : String(err));
+  }
+  return {
+    help: Boolean(values.help),
+    json: values.json,
+    yes: Boolean(values.yes),
+    mode: values.mode,
+    name: values.name,
+    framework: values.framework,
+    aiTool: values["ai-tool"],
+    serverUrl: values["server-url"],
+    appAlias: values["app-alias"],
+    clientId: values["client-id"],
+    mcpRuleName: values["mcp-rule-name"],
+    mcpRuleInsKey: values["mcp-rule-ins-key"],
+    templates: values.templates,
+    categories: values.categories,
+    conflictPolicy: values["conflict-policy"]
+  };
+}
+function isNonInteractive(args) {
+  return Boolean(
+    args.help || args.json || args.mode || args.name || args.framework || args.aiTool || args.serverUrl || args.appAlias || args.clientId || args.mcpRuleName || args.mcpRuleInsKey || args.templates || args.categories || args.conflictPolicy || args.yes
+  );
+}
+function readJsonAnswers(source) {
+  const raw = source === "-" ? fs3.readFileSync(0, "utf-8") : fs3.readFileSync(path3.resolve(source), "utf-8");
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new CliValidationError(`--json source "${source}" is not valid JSON.`);
+  }
+}
+function pickFrom(answers, key, flagValue) {
+  return answers[key] ?? flagValue;
+}
+function assertFramework(value) {
+  if (typeof value === "string" && FRAMEWORKS.includes(value)) return value;
+  throw new CliValidationError(`--framework is required and must be one of: ${FRAMEWORKS.join(", ")}`);
+}
+function parseAiTool(value) {
+  if (value === void 0 || value === "none") return null;
+  if (typeof value === "string" && AI_TOOLS.includes(value)) return value;
+  throw new CliValidationError(`--ai-tool must be one of: ${AI_TOOLS.join(", ")}, or "none"`);
+}
+function parseRequiredAiTool(value) {
+  if (typeof value === "string" && AI_TOOLS.includes(value)) return value;
+  throw new CliValidationError(
+    `--ai-tool is required for the embedded flow and must be one of: ${AI_TOOLS.join(", ")}`
+  );
+}
+function parseBoolean(value, fallback) {
+  if (value === void 0) return fallback;
+  if (value === true || value === "true") return true;
+  if (value === false || value === "false") return false;
+  throw new CliValidationError(`Expected "true" or "false", got "${String(value)}"`);
+}
+function parseCategories(value) {
+  if (value === void 0) return ALL_CATEGORIES;
+  if (Array.isArray(value)) return value;
+  const entries = String(value).split(",").map((entry) => entry.trim()).filter(Boolean);
+  const valid = new Set(ALL_CATEGORIES);
+  for (const entry of entries) {
+    if (!valid.has(entry)) {
+      throw new CliValidationError(`--categories entry "${entry}" is not one of: ${ALL_CATEGORIES.join(", ")}`);
+    }
+  }
+  return entries;
+}
+function resolveNonInteractiveUserChoices(args) {
+  const answers = args.json ? readJsonAnswers(args.json) : {};
+  const projectName = pickFrom(answers, "projectName", args.name);
+  if (typeof projectName !== "string" || !projectName) {
+    throw new CliValidationError('Project name is required (--name, or "projectName" in --json).');
+  }
+  if (!PROJECT_NAME_RE.test(projectName)) {
+    throw new CliValidationError("Invalid project name. Use lowercase letters, numbers, hyphens, and dots.");
+  }
+  const framework = assertFramework(pickFrom(answers, "framework", args.framework));
+  const aiTool = parseAiTool(pickFrom(answers, "aiTool", args.aiTool));
+  const isReactNative = framework === "react-native";
+  const includeTemplates = isReactNative ? true : parseBoolean(pickFrom(answers, "includeTemplates", args.templates), true);
+  const componentCategories = isReactNative ? ["fields", "templates", "infra"] : includeTemplates ? parseCategories(pickFrom(answers, "componentCategories", args.categories)) : [];
+  return {
+    projectName,
+    framework,
+    aiTool,
+    includeTemplates,
+    componentCategories,
+    serverUrl: pickFrom(answers, "serverUrl", args.serverUrl),
+    appAlias: pickFrom(answers, "appAlias", args.appAlias),
+    clientId: pickFrom(answers, "clientId", args.clientId),
+    mcpRuleName: pickFrom(answers, "mcpRuleName", args.mcpRuleName),
+    mcpRuleInsKey: pickFrom(answers, "mcpRuleInsKey", args.mcpRuleInsKey)
+  };
+}
+function resolveNonInteractiveEmbeddedChoices(args) {
+  const answers = args.json ? readJsonAnswers(args.json) : {};
+  const aiTool = parseRequiredAiTool(pickFrom(answers, "aiTool", args.aiTool));
+  const conflictPolicyRaw = pickFrom(answers, "conflictPolicy", args.conflictPolicy);
+  let conflictPolicy;
+  if (conflictPolicyRaw !== void 0) {
+    if (conflictPolicyRaw !== "merge" && conflictPolicyRaw !== "override") {
+      throw new CliValidationError('--conflict-policy must be "merge" or "override"');
+    }
+    conflictPolicy = conflictPolicyRaw;
+  }
+  return {
+    aiTool,
+    serverUrl: pickFrom(answers, "serverUrl", args.serverUrl),
+    appAlias: pickFrom(answers, "appAlias", args.appAlias),
+    clientId: pickFrom(answers, "clientId", args.clientId),
+    mcpRuleName: pickFrom(answers, "mcpRuleName", args.mcpRuleName),
+    mcpRuleInsKey: pickFrom(answers, "mcpRuleInsKey", args.mcpRuleInsKey),
+    conflictPolicy
+  };
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version: sdkVersion } = require2("../package.json");
+async function runNonInteractive(cwd, rawArgs) {
+  const flags = parseCliArgs(rawArgs);
+  if (flags.help) {
+    console.log(HELP_TEXT);
+    return;
+  }
+  try {
+    const mode = flags.mode ?? (detectExistingProject(cwd) ? "embedded" : "new");
+    if (mode === "embedded") {
+      const choices = resolveNonInteractiveEmbeddedChoices(flags);
+      const conflicts = collectEmbeddedConflicts(cwd, choices);
+      if (conflicts.length > 0) {
+        console.log(
+          pc.dim(
+            `Found ${conflicts.length} existing file(s); using conflict policy "${choices.conflictPolicy ?? "merge"}".`
+          )
+        );
+      }
+      await scaffoldEmbedded(choices, cwd, (message) => console.log(pc.dim(message)));
+      console.log(pc.green("Embedded flow ready!"));
+    } 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!"));
+    }
+  } catch (err) {
+    console.error(pc.red(err instanceof CliValidationError || err instanceof Error ? err.message : String(err)));
+    process.exit(1);
+  }
+}
 async function main() {
-  console.clear();
-  p.intro(pc.bgCyan(pc.black(" @pega/sdk ")));
-  p.log.info(`Using @pega/sdk v${sdkVersion}`);
   const args = process.argv.slice(2);
   const command = args[0];
   if (command !== "init") {
-    p.log.error(`Unknown command "${command ?? ""}".
+    console.error(`Unknown command "${command ?? ""}".
 
-Usage: ${pc.cyan("npx @pega/sdk init")}`);
+Usage: npx @pega/sdk init`);
     process.exit(1);
   }
   const cwd = process.cwd();
+  const rest = args.slice(1);
+  if (isNonInteractive(parseCliArgs(rest))) {
+    await runNonInteractive(cwd, rest);
+    return;
+  }
+  console.clear();
+  p.intro(pc.bgCyan(pc.black(" @pega/sdk ")));
+  p.log.info(`Using @pega/sdk v${sdkVersion}`);
   const projectMode = detectExistingProject(cwd) ? "embedded" : "new";
   if (projectMode === "embedded") {
     const continueEmbedded = await p.confirm({
@@ -1303,84 +1524,12 @@ Usage: ${pc.cyan("npx @pega/sdk init")}`);
       p.cancel("Operation cancelled.");
       process.exit(0);
     }
-    p.log.info(pc.dim("\nNow let's connect to your Pega server."));
-    const serverUrlResult = await p.text({
-      message: "What is your Pega server URL?",
-      placeholder: "https://your-pega-server.com/prweb",
-      validate(value) {
-        if (!value) return "Server URL is required.";
-        if (!value.startsWith("http")) return "Must be a valid URL starting with http:// or https://";
-      }
-    });
-    if (p.isCancel(serverUrlResult)) {
-      p.cancel("Operation cancelled.");
-      process.exit(0);
-    }
-    const serverUrl2 = serverUrlResult.replace(/\/+$/, "");
-    const appAlias2 = await p.text({
-      message: "What is your Pega application alias?",
-      placeholder: "MyApp",
-      validate(value) {
-        if (!value) return "Application alias is required.";
-      }
-    });
-    if (p.isCancel(appAlias2)) {
-      p.cancel("Operation cancelled.");
-      process.exit(0);
-    }
-    const clientId2 = await p.text({
-      message: "What is the OAuth Client ID for your app?",
-      placeholder: "Your OAuth 2.0 client identifier",
-      validate(value) {
-        if (!value) return "Client ID is required for authentication.";
-      }
-    });
-    if (p.isCancel(clientId2)) {
-      p.cancel("Operation cancelled.");
-      process.exit(0);
-    }
-    const userIdentifier = await p.text({
-      message: "What is the operator ID for the embedded session?",
-      placeholder: "user@yourapp",
-      validate(value) {
-        if (!value) return "Operator ID is required.";
-      }
-    });
-    if (p.isCancel(userIdentifier)) {
-      p.cancel("Operation cancelled.");
-      process.exit(0);
-    }
-    p.log.info(pc.dim("\nIf you've configured an MCP server for this app, we can wire it up too (optional)."));
-    const mcpRuleNameResult = await p.text({
-      message: "What is your Pega MCP rule name? (press Enter to skip)",
-      placeholder: "SDKMCP"
-    });
-    if (p.isCancel(mcpRuleNameResult)) {
-      p.cancel("Operation cancelled.");
-      process.exit(0);
-    }
-    const mcpRuleInsKeyResult = await p.text({
-      message: "What is your Pega MCP rule instance key? (press Enter to skip)",
-      placeholder: "@baseclass!SDKMCP"
-    });
-    if (p.isCancel(mcpRuleInsKeyResult)) {
-      p.cancel("Operation cancelled.");
-      process.exit(0);
-    }
-    const mcpRuleName2 = mcpRuleNameResult || void 0;
-    const mcpRuleInsKey2 = mcpRuleInsKeyResult || void 0;
     const embeddedTargetDir = cwd;
     p.note(
       [
         `${pc.bold("Mode")}:          Embed Pega flow`,
         `${pc.bold("Directory")}:     ${embeddedTargetDir}`,
-        `${pc.bold("AI Tool")}:       ${embeddedAiTool}`,
-        `${pc.bold("Server")}:        ${serverUrl2}`,
-        `${pc.bold("App Alias")}:     ${appAlias2}`,
-        `${pc.bold("Client ID")}:     ${clientId2}`,
-        `${pc.bold("Operator")}:      ${userIdentifier}`,
-        `${pc.bold("MCP Rule")}:      ${mcpRuleName2 ?? pc.dim("(not configured \u2014 markers left in generated file)")}`,
-        `${pc.bold("MCP Ins Key")}:   ${mcpRuleInsKey2 ?? pc.dim("(not configured \u2014 markers left in generated file)")}`
+        `${pc.bold("AI Tool")}:       ${embeddedAiTool}`
       ].join("\n"),
       "Configuration"
     );
@@ -1393,13 +1542,7 @@ Usage: ${pc.cyan("npx @pega/sdk init")}`);
       process.exit(0);
     }
     const embeddedChoices = {
-      aiTool: embeddedAiTool,
-      serverUrl: serverUrl2,
-      appAlias: appAlias2,
-      clientId: clientId2,
-      userIdentifier,
-      mcpRuleName: mcpRuleName2,
-      mcpRuleInsKey: mcpRuleInsKey2
+      aiTool: embeddedAiTool
     };
     let conflicts = [];
     try {
@@ -1519,62 +1662,6 @@ Usage: ${pc.cyan("npx @pega/sdk init")}`);
       process.exit(0);
     }
     aiTool = aiToolResult;
-    p.log.info(pc.dim("\nIf you'd like the new project to include an MCP config, we need a few connection details."));
-    const serverUrlResult = await p.text({
-      message: "What is your Pega server URL?",
-      placeholder: "https://your-pega-server.com/prweb",
-      validate(value) {
-        if (!value) return "Server URL is required.";
-        if (!value.startsWith("http")) return "Must be a valid URL starting with http:// or https://";
-      }
-    });
-    if (p.isCancel(serverUrlResult)) {
-      p.cancel("Operation cancelled.");
-      process.exit(0);
-    }
-    const appAliasResult = await p.text({
-      message: "What is your Pega application alias?",
-      placeholder: "MyApp",
-      validate(value) {
-        if (!value) return "Application alias is required.";
-      }
-    });
-    if (p.isCancel(appAliasResult)) {
-      p.cancel("Operation cancelled.");
-      process.exit(0);
-    }
-    const clientIdResult = await p.text({
-      message: "What is the OAuth Client ID for your app?",
-      placeholder: "Your OAuth 2.0 client identifier",
-      validate(value) {
-        if (!value) return "Client ID is required for authentication.";
-      }
-    });
-    if (p.isCancel(clientIdResult)) {
-      p.cancel("Operation cancelled.");
-      process.exit(0);
-    }
-    const mcpRuleNameResult = await p.text({
-      message: "What is your Pega MCP rule name? (press Enter to skip)",
-      placeholder: "SDKMCP"
-    });
-    if (p.isCancel(mcpRuleNameResult)) {
-      p.cancel("Operation cancelled.");
-      process.exit(0);
-    }
-    const mcpRuleInsKeyResult = await p.text({
-      message: "What is your Pega MCP rule instance key? (press Enter to skip)",
-      placeholder: "@baseclass!SDKMCP"
-    });
-    if (p.isCancel(mcpRuleInsKeyResult)) {
-      p.cancel("Operation cancelled.");
-      process.exit(0);
-    }
-    serverUrl = String(serverUrlResult).replace(/\/+$/, "");
-    appAlias = String(appAliasResult);
-    clientId = String(clientIdResult);
-    mcpRuleName = String(mcpRuleNameResult) || void 0;
-    mcpRuleInsKey = String(mcpRuleInsKeyResult) || void 0;
   }
   const framework = await p.select({
     message: "Select a UI framework for your Pega SDK project:",
@@ -1659,7 +1746,7 @@ Usage: ${pc.cyan("npx @pega/sdk init")}`);
       componentCategories = categories;
     }
   }
-  const targetDir = path3.resolve(process.cwd(), projectName);
+  const targetDir = path4.resolve(process.cwd(), projectName);
   p.note(
     [
       `${pc.bold("Project")}:       ${projectName}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pega/sdk",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "Scaffold a Pega SDK application project",
   "type": "module",
   "bin": {

package/templates/react-sdk-reference/.ai-common/agents/embedded-flow-expert.md

@@ -53,6 +53,10 @@ Determine which workflow governs the request, then execute it by reading the ref
 
 ⛔ **This step MUST complete before any component generation begins.** Do NOT use hardcoded component lists. Both the case type and the component list MUST come from the Pega server.
 
+### Step 0.0 — Ensure the Pega server connection is configured
+
+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, and otherwise gathers the missing values from the user and writes them into the MCP config and `sdk-config.json` before this step continues.
+
 ### Step 0.1 — Check for a case type in the prompt
 
 Scan the user's message for a **Pega case type class name** (hyphen-separated segments like `DIXL-MediaCo-Work-NewService`). Note whether one was found — it will be needed in Step 0.2.

package/templates/react-sdk-reference/.ai-common/global/ai-agent-instructions-embedded.md

@@ -47,7 +47,7 @@ Pega SDK packages (`.tgz` files) have been added to the project root and referen
 
 ### SDK Configuration
 
-`sdk-config.json` contains connection details for the Pega server. The customer must fill in their server URL, app alias, OAuth client ID, and case type.
+`sdk-config.json` contains connection details for the Pega server. The AI assistant gathers the server URL, app alias, OAuth client ID, and (when the MCP configuration requires one) a client secret from the user in chat the first time a workflow needs them, and fills them in automatically — see `{{SKILL_DIR}}/connect-pega-server.md`. The case type is resolved from the server during the embedded flow itself.
 
 ---
 

package/templates/react-sdk-reference/.ai-common/mcp/cursor.mcp.json

@@ -4,7 +4,7 @@
       "url": "{InfinityURL}/app/{AppAlias}/api/service/v1/mcp/{MCPRuleInsKey}",
       "auth": {
         "clientId": "{ClientId}",
-        "clientSecret": "<YOUR_CLIENT_SECRET>"
+        "clientSecret": "{ClientSecret}"
       }
     }
   }

package/templates/react-sdk-reference/.ai-common/prompts/generate-all-components.md

@@ -55,6 +55,10 @@ Once design system, base folder, and type scope are resolved, continue to Step 0
 
 ⛔ **This step MUST complete before anything is read, installed, or written.** A portal renders a specific set of components, and generating the full catalogue produces components the portal will never mount. Do NOT use a hardcoded component list, and do NOT infer one from the project's existing folders.
 
+### 0.5.0 — Ensure the Pega server connection is configured
+
+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, and otherwise gathers the missing values from the user and writes them into the MCP config and `sdk-config.json` before this step continues.
+
 ### 0.5.1 — Resolve the portal
 
 Execute the data source **`D_pyAvailablePortals`**, which returns the portals available in the application. Pass the name exactly as written — this data page is part of the Pega platform and does not vary between installations.
@@ -70,6 +74,7 @@ The response's `pxResults` array holds one entry per portal. Then:
 1. If the user's message did NOT name a portal, present the returned portals as a numbered pick-list and ask which one to generate for.
 2. If the user's message DID name one, confirm it appears in the response. If it does not, show what the server returned and ask the user to choose from that list. Never proceed on an unverified portal name.
 3. Record the confirmed entry's **`pyPortalLayout`** value. This — not the display label shown to the user — is what Steps 0.5.3 and 0.5.4 pass to the server as `PortalName`; carry it forward exactly as the data page returned it.
+4. Write the confirmed `pyPortalLayout` value into `sdk-config.json` field `serverConfig.appPortal`.
 
 ### 0.5.2 — Ask what to convert
 
@@ -89,10 +94,20 @@ Present the returned pages as a **checkbox list** (label each with its `pyRuleNa
 
 For **each selected page**, resolve its components by its `pxObjClass`:
 
-| `pxObjClass`                                                 | Data source                       | Parameters                                         | Components are in |
-| ------------------------------------------------------------ | --------------------------------- | -------------------------------------------------- | ----------------- |
-| `Rule-UI-View`                                               | `D_pyViewDependencies`            | `ViewName = pyRuleName`, `ViewClass = pyClassName` | `pxDependencies`  |
-| `Rule-UI-View-LandingPage` (and anything else — the default) | `D_pyLandingPageComponentsByType` | `RuleName = pyRuleName`, `ClassName = pyClassName` | `pxResults`       |
+Apply this dispatch as an exact, mutually exclusive decision for every page. Do not choose a data source based on the page label, rule name, or a guessed similarity:
+
+1. If `pxObjClass` is exactly `Rule-UI-View`, execute **only** `D_pyViewDependencies` with `ViewName = pyRuleName` and `ViewClass = pyClassName`. Read component names from `pxDependencies`.
+2. Else if `pxObjClass` is exactly `Rule-UI-View-LandingPage`, execute **only** `D_pyLandingPageComponentsByType` with `RuleName = pyRuleName` and `ClassName = pyClassName`. Read component names from `pxResults`.
+3. Else, do not execute either data source. Report the unsupported `pxObjClass`, preserve the page in the selection summary, and ask how to proceed. Never route an unknown class through the landing-page data source as a default.
+
+The required mapping is:
+
+| Exact `pxObjClass`         | Data source                       | Parameters                                         | Components are in |
+| -------------------------- | --------------------------------- | -------------------------------------------------- | ----------------- |
+| `Rule-UI-View`             | `D_pyViewDependencies`            | `ViewName = pyRuleName`, `ViewClass = pyClassName` | `pxDependencies`  |
+| `Rule-UI-View-LandingPage` | `D_pyLandingPageComponentsByType` | `RuleName = pyRuleName`, `ClassName = pyClassName` | `pxResults`       |
+
+For a page whose `pxObjClass` is `Rule-UI-View`, it is a workflow error to call `D_pyLandingPageComponentsByType`; stop and correct the dispatch before continuing. Likewise, do not call `D_pyViewDependencies` for `Rule-UI-View-LandingPage`.
 
 Do not supply `ApplicationName` or `ApplicationVersion` to `D_pyLandingPageComponentsByType` — ignore those parameters. Make one call per selected page, even when two pages resolve to the same data source. Discard malformed entries (anything that is not a plain component-name identifier) from each response, then union the results across all selected pages and drop duplicates. Keep a note of which page(s) contributed each component — Step 0.5.5 reports it.
 

package/templates/react-sdk-reference/.ai-common/skills/connect-pega-server.md

@@ -0,0 +1,54 @@
+---
+ai-description: Ensure the Pega server connection (MCP config + sdk-config.json) is configured before any workflow executes a live Pega data source. Not a standalone flow — invoked as a prerequisite step by other skills/prompts.
+---
+
+# Pega Server Connection Gate
+
+Run this **before** the first Pega data source is executed in a chat session. It ensures the MCP server this session talks to, and `sdk-config.json`, both carry real connection values instead of the placeholder markers the project scaffolding step leaves behind. Scaffolding never asks for these — this gate is where they are actually collected, the first time a workflow needs them.
+
+## 1. Locate the MCP config file
+
+Find the file this session's AI tool reads its Pega MCP server list from. Do not assume a fixed name or path, and do not ask the user which file to edit — discover it by what it contains: a server entry whose key starts with `pega-`, holding a `url` that points at an `/api/service/v1/mcp/` endpoint. Search the project for a file matching that shape.
+
+## 2. Check whether it is already configured
+
+Read that file and `sdk-config.json`. Treat the connection as **already configured** only when none of the following markers remain, literally, in either file: `{InfinityURL}`, `{AppAlias}`, `{MCPRuleName}`, `{MCPRuleInsKey}`, `{ClientId}`, `{ClientSecret}`, and `sdk-config.json`'s `serverConfig.infinityRestServerUrl` / `serverConfig.appAlias` / `authConfig.mashupClientId` are non-empty.
+
+If already configured, skip the rest of this gate and continue with the workflow that invoked it.
+
+## 3. Ask only for what is still missing
+
+Check each value independently — ask only for the ones still a marker or blank, never re-ask for a value already present:
+
+- Pega server URL
+- Application alias
+- OAuth client ID
+- MCP rule name
+- MCP rule instance key
+- **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.
+
+Ask these as a single batch of questions, not one at a time.
+
+## 4. Write the values
+
+**MCP config file** — replace each marker with the value collected for it, and rename the `pega-{MCPRuleName}` server key using the real rule name:
+
+- `{InfinityURL}` → server URL
+- `{AppAlias}` → application alias
+- `{MCPRuleName}` → MCP rule name (in both the server key and the URL path)
+- `{MCPRuleInsKey}` → MCP rule instance key
+- `{ClientId}` → client ID, if the entry has an `auth` block
+- `{ClientSecret}` → client secret, if the `auth` block has that field
+
+**`sdk-config.json`** — write into the existing structure, do not create new fields:
+
+- `serverConfig.infinityRestServerUrl` → server URL
+- `serverConfig.appAlias` → application alias
+- `authConfig.mashupClientId` → client ID
+- `authConfig.portalClientId` → client ID (same value as `mashupClientId`)
+
+Never write the client secret into `sdk-config.json` — it belongs only in the MCP config file's `auth.clientSecret`.
+
+## 5. Tell the user to reconnect
+
+Most AI tools read their MCP config once at startup. After writing these values, tell the user the MCP server configuration changed and they need to reload or reconnect it (tool-dependent — e.g. restarting the MCP connection or reloading the window) before their request can proceed, and ask them to retry once reconnected.

package/templates/react-sdk-reference/package.minimal.json

@@ -9,7 +9,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@pega/auth": "file:pega-auth-0.2.42.tgz",
+    "@pega/auth": "file:pega-auth-0.2.44.tgz",
     "@pega/constellationjs": "file:pega-constellationjs-0.26.3-local.tgz",
     "@pega/sdk-react": "file:pega-sdk-react-0.1.0.tgz",
     "@pega/sdk-types": "file:pega-sdk-types-0.1.0.tgz",