@salesforce/b2c-dx-mcp 0.3.2 → 0.4.1

package/dist/tools/page-designer-decorator/rules/2a-auto-mode.js

@@ -0,0 +1,87 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+export function renderAutoMode(context) {
+    return `# Auto Mode - Page Designer Decorator Generation
+
+## LLM INSTRUCTIONS
+
+### Auto Mode Behavior
+
+**Single-Step Execution:**
+- NO user interaction required
+- NO questions to ask
+- Analyze component automatically
+- Auto-select all suitable props
+- Auto-infer types based on naming patterns
+- Generate code immediately
+
+**Auto-Selection Criteria:**
+- ✅ Include: Simple props (string, number, boolean)
+- ❌ Exclude: Complex types (objects, arrays, functions)
+- ❌ Exclude: UI-only props (className, style, etc.)
+
+**Auto-Inference Patterns:**
+- \`*Url\`, \`*Link\` → \`url\` type
+- \`*Image\`, \`*Icon\` → \`image\` type
+- \`is*\`, \`has*\`, \`enable*\`, \`show*\` → \`boolean\` type (default: false)
+- \`*Size\` → \`enum\` type (values: ['default', 'primary', 'secondary'])
+- \`*Variant\` → \`enum\` type (values: ['default', 'primary', 'secondary'])
+
+**Regions:**
+- NOT configured in auto mode
+- User must use interactive mode for regions
+
+### Component Analysis Summary
+
+**Component Name**: ${context.componentName}
+**File**: ${context.file}
+**Component ID**: ${context.componentId}
+**Selected Props**: ${context.selectedPropCount}
+**Auto-configured**: ${context.autoConfigCount}
+**Auto-inferred**: ${context.autoInferredCount}
+
+${context.hasNoSuitableProps
+        ? `⚠️ **No suitable props found**. The component has only complex or UI-only props.
+Consider adding new attributes manually or using interactive mode.`
+        : ''}
+
+---
+
+# USER-FACING RESPONSE
+
+# ✅ Page Designer Decorators Generated (Auto Mode)
+
+## Auto-Configuration Summary
+
+- **Component**: \`${context.componentName}\`
+- **Component ID**: \`${context.componentId}\`
+- **File**: \`${context.file}\`
+- **Selected Props**: ${context.selectedProps}
+- **Auto-configured**: ${context.autoConfigCount}
+- **Auto-inferred**: ${context.autoInferredCount}
+
+${context.hasNoSuitableProps
+        ? `⚠️ **No suitable props found**. The component has only complex or UI-only props.
+Consider adding new attributes manually or using interactive mode.`
+        : ''}
+
+## Generated Code
+
+Add this metadata class to your component file:
+
+\`\`\`typescript
+${context.decoratorCode}
+\`\`\`
+
+## Next Steps
+
+1. **Add the code** to \`${context.file}\` (after imports, before component)
+2. **Update component props** to make them optional and add type unions as needed
+3. **Generate metadata**: Run \`sfnext generate-cartridge --project-directory .\`
+4. **Deploy cartridge**: Run \`sfnext deploy-cartridge --project-directory .\`
+5. **Verify in Business Manager**: Check Components > ${context.componentGroup} > ${context.componentName}`;
+}
+//# sourceMappingURL=2a-auto-mode.js.map

package/dist/tools/page-designer-decorator/rules/2b-0-interactive-overview.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Interactive mode workflow overview
+ */
+export declare function renderInteractiveOverview(): string;

package/dist/tools/page-designer-decorator/rules/2b-0-interactive-overview.js

@@ -0,0 +1,55 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+/**
+ * Interactive mode workflow overview
+ */
+export function renderInteractiveOverview() {
+    return `# ⚠️ MANDATORY: Adding Page Designer Support
+
+## 🚨 CRITICAL: Multi-Step Workflow
+
+**YOU MUST FOLLOW THIS WORKFLOW:**
+
+1. **analyze**: Present component analysis and ask configuration questions
+   - Component identity (ID, name, description, group)
+   - Which existing props to expose
+   - Whether to add new attributes
+
+2. **select_props**: Confirm user's selections
+   - Show what was selected
+   - Confirm component metadata
+   - Prepare for type configuration
+
+3. **configure_attrs**: Configure attribute types
+   - Show auto-inferred types
+   - Ask for explicit type configuration where needed
+   - Collect defaults and enum values
+
+4. **configure_regions**: Configure regions (optional)
+   - Ask if component needs nested content areas
+   - Configure region definitions if needed
+
+5. **confirm_generation**: Generate final decorator code
+   - Render decorators with all configurations
+   - Show code to user
+
+**VIOLATION OF THIS WORKFLOW IS A CRITICAL ERROR.**
+
+## Workflow Enforcement
+
+- Each step must complete before proceeding to the next
+- User must confirm or provide input at each step
+- Do not make assumptions about user preferences
+- Do not skip steps, even if the answer seems obvious
+
+## Next Step Instructions
+
+After presenting analysis, you MUST:
+1. Wait for user's answers to ALL questions
+2. Call tool again with step: "select_props" and user's responses in conversationContext
+3. NEVER proceed to code generation without completing all steps`;
+}
+//# sourceMappingURL=2b-0-interactive-overview.js.map

package/dist/tools/page-designer-decorator/rules/2b-1-interactive-analyze.d.ts

@@ -0,0 +1,22 @@
+export interface PropInfo {
+    name: string;
+    type: string;
+    optional: boolean;
+}
+export interface AnalyzeStepContext {
+    componentName: string;
+    file: string;
+    hasDecorators: boolean;
+    interfaceName?: string;
+    totalProps: number;
+    exportType: string;
+    hasEditableProps: boolean;
+    editableProps: PropInfo[];
+    hasComplexProps: boolean;
+    complexProps: PropInfo[];
+    hasUIProps: boolean;
+    uiProps: PropInfo[];
+    suggestedComponentId: string;
+    suggestedComponentName: string;
+}
+export declare function renderAnalyzeStep(context: AnalyzeStepContext): string;

package/dist/tools/page-designer-decorator/rules/2b-1-interactive-analyze.js

@@ -0,0 +1,109 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+export function renderAnalyzeStep(context) {
+    return `# Step 1: Component Analysis
+
+## LLM INSTRUCTIONS
+
+### Component Analysis Results
+
+**Component Name**: ${context.componentName}
+**File**: ${context.file}
+**Has Decorators**: ${context.hasDecorators ? 'Yes (STOP - already decorated)' : 'No (proceed)'}
+**Props Interface**: ${context.interfaceName || 'None found'}
+**Total Props**: ${context.totalProps}
+
+${context.hasDecorators
+        ? `⚠️ **CRITICAL**: Component already has Page Designer decorators.
+**ACTION**: Stop here and inform user. Do not proceed with generation.`
+        : ''}
+
+### Next Actions (LLM)
+
+1. Present the analysis to the user
+2. Ask all configuration questions (component identity, props selection, new properties)
+3. Wait for user's complete response
+4. THEN call tool again with step: "select_props" with collected answers
+
+---
+
+# USER-FACING RESPONSE
+
+${context.hasDecorators
+        ? `# Analysis: ${context.componentName}
+
+✅ **This component already has Page Designer support.**
+
+The component has existing decorators (@Component, @AttributeDefinition, etc.).
+
+Would you like to modify the existing decorators instead?`
+        : `# Analysis: ${context.componentName}
+
+## Current State
+
+- **Component**: \`${context.componentName}\`
+- **File**: \`${context.file}\`
+- **Props Interface**: \`${context.interfaceName || 'None found'}\`
+- **Export Type**: ${context.exportType}
+
+## Existing Properties Analysis
+
+${context.hasEditableProps
+            ? `### ✅ Suitable for Page Designer:
+
+${context.editableProps.map((prop) => `- \`${prop.name}\` (${prop.type})${prop.optional ? ' - optional' : ''}`).join('\n')}`
+            : '### ⚠️ No suitable properties found'}
+
+${context.hasComplexProps
+            ? `### ⚠️ Complex (needs simplification):
+
+${context.complexProps.map((prop) => `- \`${prop.name}\` (${prop.type}) - Too complex for Page Designer`).join('\n')}
+
+These complex types cannot be used directly. Consider creating simpler alternatives.`
+            : ''}
+
+${context.hasUIProps
+            ? `### 🎨 UI Props (typically not exposed):
+
+${context.uiProps.map((prop) => `- \`${prop.name}\` (${prop.type})`).join('\n')}
+
+These are styling/layout props, usually not exposed to Page Designer.`
+            : ''}
+
+## Configuration Questions
+
+### 1️⃣ Component Identity
+
+I suggest:
+- **ID**: \`${context.suggestedComponentId}\`
+- **Name**: "${context.suggestedComponentName}"
+- **Description**: *[Please provide a description]*
+- **Group**: \`odyssey_base\` (default) or specify custom group
+
+✏️ Are these acceptable, or would you like to change them?
+
+### 2️⃣ Existing Properties
+
+${context.hasEditableProps
+            ? `**Which properties should be editable in Page Designer?**
+
+${context.editableProps.map((prop) => `- [ ] \`${prop.name}\` - ${prop.type}`).join('\n')}`
+            : '⚠️ No existing properties are suitable.'}
+
+### 3️⃣ New Properties
+
+**Should I add any new properties** that don't exist in the component interface?
+
+Examples:
+- Button text, labels, or headings
+- Toggle flags (show/hide elements)
+- Configuration options
+
+---
+
+**Please answer these questions to proceed.**`}`;
+}
+//# sourceMappingURL=2b-1-interactive-analyze.js.map

package/dist/tools/page-designer-decorator/rules/2b-2-interactive-select-props.d.ts

@@ -0,0 +1,21 @@
+export interface NewAttribute {
+    name: string;
+    description?: string;
+    required?: boolean;
+}
+export interface SelectPropsContext {
+    componentMetadata: {
+        id: string;
+        name: string;
+        description: string;
+        group?: string;
+    };
+    selectedProps: string[];
+    newAttributes: NewAttribute[];
+    selectedPropsCount: number;
+    newAttributesCount: number;
+    totalAttributeCount: number;
+    hasSelectedProps: boolean;
+    hasNewAttributes: boolean;
+}
+export declare function renderSelectPropsConfirmation(context: SelectPropsContext): string;

package/dist/tools/page-designer-decorator/rules/2b-2-interactive-select-props.js

@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+export function renderSelectPropsConfirmation(context) {
+    return `# Step 2: Selection Confirmation
+
+## LLM INSTRUCTIONS
+
+### Purpose
+Present a clear confirmation of the user's selections from Step 1 (analyze).
+
+### Context Provided
+- Component identity (id, name, description, group)
+- Array of selected existing prop names
+- Array of new attributes to add
+- Counts and flags
+
+### Next Actions
+After showing confirmation, instruct user to confirm proceeding to type configuration.
+
+---
+
+# USER-FACING RESPONSE
+
+# ✅ Selection Confirmed
+
+## Component Configuration
+
+- **ID**: \`${context.componentMetadata.id}\`
+- **Name**: "${context.componentMetadata.name}"
+- **Description**: "${context.componentMetadata.description}"
+- **Group**: \`${context.componentMetadata.group || 'odyssey_base'}\`
+
+${context.hasSelectedProps
+        ? `## 📋 Selected Existing Props (${context.selectedPropsCount})
+
+${context.selectedProps.map((prop) => `- \`${prop}\``).join('\n')}`
+        : `## 📋 Selected Existing Props
+
+None selected.`}
+
+${context.hasNewAttributes
+        ? `## ➕ New Attributes to Add (${context.newAttributesCount})
+
+${context.newAttributes.map((attr) => `- \`${attr.name}\`${attr.description ? ` - ${attr.description}` : ''}${attr.required ? ' (required)' : ''}`).join('\n')}`
+        : `## ➕ New Attributes to Add
+
+None requested.`}
+
+---
+
+## 🎯 Next Step: Attribute Configuration
+
+Now I'll analyze the types for these ${context.totalAttributeCount} attribute(s) and help you configure them for Page Designer.
+
+**Please confirm**: Ready to proceed with type configuration? (Say "yes" or "proceed")`;
+}
+//# sourceMappingURL=2b-2-interactive-select-props.js.map

package/dist/tools/page-designer-decorator/rules/2b-3-interactive-configure-attrs.d.ts

@@ -0,0 +1,27 @@
+export interface TypeSuggestion {
+    type: string;
+    priority: string;
+    reason: string;
+}
+export interface ConfigureAttrsContext {
+    totalAttributes: number;
+    autoInferredCount: number;
+    needsConfigCount: number;
+    hasAutoInferred: boolean;
+    autoInferredAttrs: Array<{
+        name: string;
+        tsType: string;
+    }>;
+    hasNeedsConfig: boolean;
+    needsConfigAttrs: Array<{
+        name: string;
+        tsType: string;
+        source: string;
+        hasSuggestions: boolean;
+        suggestions: TypeSuggestion[];
+        suggestedTypes: string;
+        humanReadableName: string;
+        hasEnumSuggestion: boolean;
+    }>;
+}
+export declare function renderConfigureAttrs(context: ConfigureAttrsContext): string;

package/dist/tools/page-designer-decorator/rules/2b-3-interactive-configure-attrs.js

@@ -0,0 +1,68 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+export function renderConfigureAttrs(context) {
+    return `# Step 2: Attribute Configuration
+
+## LLM INSTRUCTIONS
+
+### Analysis Complete
+
+Total attributes to configure: ${context.totalAttributes}
+Auto-inferred: ${context.autoInferredCount}
+Need configuration: ${context.needsConfigCount}
+
+### Next Steps for LLM
+
+**WAIT for user to:**
+1. Provide explicit type overrides (if desired)
+2. Provide custom names/descriptions (if desired)
+3. Provide enum values (if applicable)
+4. Or confirm "use defaults"
+
+**THEN** call tool again with step: "configure_regions"
+
+---
+
+# USER-FACING RESPONSE
+
+# Attribute Configuration
+
+${context.hasAutoInferred
+        ? `## ✅ Auto-Configured Attributes
+
+These attributes will use auto-inferred types (no explicit configuration needed):
+
+${context.autoInferredAttrs.map((attr) => `- **${attr.name}** (${attr.tsType}) → Auto-inferred as Page Designer type`).join('\n')}`
+        : ''}
+
+${context.hasNeedsConfig
+        ? `## ⚙️ Attributes Needing Configuration
+
+${context.needsConfigAttrs
+            .map((attr, index) => `### ${index + 1}. \`${attr.name}\`
+
+- **TypeScript Type**: \`${attr.tsType}\`
+- **Source**: ${attr.source}
+
+${attr.hasSuggestions
+            ? `**Recommendations**:
+
+${attr.suggestions.map((s) => `- **${s.type}** (${s.priority} priority): ${s.reason}`).join('\n')}`
+            : ''}
+
+**Questions**:
+- What Page Designer type should this be? (${attr.suggestedTypes})
+- Custom display name? (default: "${attr.humanReadableName}")
+- Default value?
+${attr.hasEnumSuggestion ? '- Enum values? (e.g., ["option1", "option2", "option3"])' : ''}`)
+            .join('\n\n')}`
+        : ''}
+
+---
+
+**Please provide configuration for attributes that need it, or say "use defaults" to proceed.**`;
+}
+//# sourceMappingURL=2b-3-interactive-configure-attrs.js.map

package/dist/tools/page-designer-decorator/rules/2b-4-interactive-configure-regions.d.ts

@@ -0,0 +1,4 @@
+export interface ConfigureRegionsContext {
+    componentName: string;
+}
+export declare function renderConfigureRegions(context: ConfigureRegionsContext): string;

package/dist/tools/page-designer-decorator/rules/2b-4-interactive-configure-regions.js

@@ -0,0 +1,65 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+export function renderConfigureRegions(context) {
+    return `# Step 3: Region Configuration
+
+## LLM INSTRUCTIONS
+
+### 🚨 CRITICAL: Ask User About Regions
+
+**YOU MUST:**
+1. Ask user if component needs regions for nested content
+2. If YES, ask for region configurations:
+   - Region ID (e.g., "main", "sidebar", "footer")
+   - Region name (display name)
+   - Description (optional)
+   - Max components (optional)
+   - Component type filters (optional)
+3. Wait for user response
+4. THEN call tool again with step: "confirm_generation" and regionConfig filled
+
+### Region Context
+
+Regions allow business users to nest other components inside this component.
+Examples: Hero with content slots, Layout containers, Section wrappers
+
+---
+
+# USER-FACING RESPONSE
+
+# Step 3: Region Configuration
+
+**Component**: ${context.componentName}
+
+## About Regions
+
+Regions define areas where business users can insert other components in Page Designer.
+Use regions for:
+- Layout containers (e.g., grid, flex layouts)
+- Content areas with multiple components
+- Sections that need nested content
+
+**Does this component need regions for nested content?**
+
+Examples:
+- ✅ **YES** for: Layout, Container, Section, Grid
+- ❌ **NO** for: Button, Image, Text, ProductCarousel
+
+---
+
+**Please answer:**
+1. Does this component need regions? (yes/no)
+2. If yes, provide region configuration(s)
+
+**Region Configuration Example:**
+\`\`\`
+- id: "main"
+  name: "Main Content"
+  description: "Primary content area"
+  maxComponents: 10
+\`\`\``;
+}
+//# sourceMappingURL=2b-4-interactive-configure-regions.js.map

package/dist/tools/page-designer-decorator/rules/2b-5-interactive-confirm-generation.d.ts

@@ -0,0 +1,11 @@
+export interface ConfirmGenerationContext {
+    decoratorCode: string;
+    componentName: string;
+    componentId: string;
+    componentGroup: string;
+    file: string;
+    attributeCount: number;
+    hasRegions: boolean;
+    regionCount?: number;
+}
+export declare function renderConfirmGeneration(context: ConfirmGenerationContext): string;

package/dist/tools/page-designer-decorator/rules/2b-5-interactive-confirm-generation.js

@@ -0,0 +1,92 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+export function renderConfirmGeneration(context) {
+    return `# Step 5: Code Generation
+
+## LLM INSTRUCTIONS
+
+### Purpose
+Present the generated Page Designer decorator code and next steps.
+
+### Context Provided
+- Complete generated metadata class with decorators
+- Component name, ID, group
+- File path, attribute count, region info
+
+### Next Actions
+1. Show the generated code
+2. Provide clear next steps for deployment
+3. Optionally offer to add code to the file
+
+---
+
+# USER-FACING RESPONSE
+
+# ✅ Page Designer Decorators Generated
+
+## Generated Code
+
+Add this metadata class to \`${context.file}\`:
+
+\`\`\`typescript
+${context.decoratorCode}
+\`\`\`
+
+## Summary
+
+- **Component**: ${context.componentName}
+- **Component ID**: \`${context.componentId}\`
+- **Group**: \`${context.componentGroup}\`
+- **Attributes**: ${context.attributeCount}
+${context.hasRegions ? `- **Regions**: ${context.regionCount} configured` : ''}
+
+## Next Steps
+
+### 1. Add the Code
+
+Add the generated metadata class to \`${context.file}\`:
+- Place it **after imports**
+- Place it **before the component definition**
+
+### 2. Update Component Props (if needed)
+
+Make decorated props optional in your component interface:
+
+\`\`\`typescript
+interface ${context.componentName}Props {
+    title?: string;  // Add ? if attribute is not required
+    // ... other props
+}
+\`\`\`
+
+### 3. Generate Cartridge Metadata
+
+\`\`\`bash
+cd packages/template-retail-rsc-app
+pnpm sfnext generate-cartridge --project-directory .
+\`\`\`
+
+This creates JSON files in \`cartridges/app_storefrontnext_base/cartridge/experience/components/\`.
+
+### 4. Deploy Cartridge
+
+\`\`\`bash
+pnpm sfnext deploy-cartridge --project-directory .
+\`\`\`
+
+### 5. Verify in Business Manager
+
+1. Log into Business Manager
+2. Navigate to: **Merchant Tools > Site > Page Designer**
+3. Find your component: **Components > ${context.componentGroup} > ${context.componentName}**
+4. Verify all attributes appear correctly
+5. Test editing a page with your component
+
+---
+
+**Would you like me to add this code to your component file?**`;
+}
+//# sourceMappingURL=2b-5-interactive-confirm-generation.js.map

package/dist/tools/page-designer-decorator/rules.d.ts

@@ -0,0 +1,51 @@
+import { type ModeSelectionContext } from './rules/1-mode-selection.js';
+import { type AnalyzeStepContext } from './rules/2b-1-interactive-analyze.js';
+import { type SelectPropsContext } from './rules/2b-2-interactive-select-props.js';
+import { type ConfigureAttrsContext } from './rules/2b-3-interactive-configure-attrs.js';
+import { type ConfigureRegionsContext } from './rules/2b-4-interactive-configure-regions.js';
+import { type ConfirmGenerationContext } from './rules/2b-5-interactive-confirm-generation.js';
+import { type AutoModeContext } from './rules/2a-auto-mode.js';
+/**
+ * Page Designer decorator rules - type-safe, zero dependencies
+ */
+export declare const pageDesignerDecoratorRules: {
+    /**
+     * Renders the mode selection prompt
+     */
+    getModeSelectionInstructions(context: ModeSelectionContext): string;
+    /**
+     * Renders the interactive mode workflow overview
+     */
+    getInteractiveOverview(): string;
+    /**
+     * Renders Interactive Analyze step instructions
+     */
+    getAnalyzeInstructions(context: AnalyzeStepContext): string;
+    /**
+     * Renders Interactive Select Props step confirmation
+     */
+    getSelectPropsConfirmation(context: SelectPropsContext): string;
+    /**
+     * Renders Interactive Configure Attributes step instructions
+     */
+    getConfigureAttrsInstructions(context: ConfigureAttrsContext): string;
+    /**
+     * Renders Interactive Configure Regions step instructions
+     */
+    getConfigureRegionsInstructions(context: ConfigureRegionsContext): string;
+    /**
+     * Renders Interactive Confirm Generation step (final code presentation)
+     */
+    getConfirmGenerationInstructions(context: ConfirmGenerationContext): string;
+    /**
+     * Renders Auto Mode instructions
+     */
+    getAutoModeInstructions(context: AutoModeContext): string;
+};
+export type { ModeSelectionContext } from './rules/1-mode-selection.js';
+export type { AutoModeContext } from './rules/2a-auto-mode.js';
+export type { AnalyzeStepContext } from './rules/2b-1-interactive-analyze.js';
+export type { SelectPropsContext } from './rules/2b-2-interactive-select-props.js';
+export type { ConfigureAttrsContext } from './rules/2b-3-interactive-configure-attrs.js';
+export type { ConfigureRegionsContext } from './rules/2b-4-interactive-configure-regions.js';
+export type { ConfirmGenerationContext } from './rules/2b-5-interactive-confirm-generation.js';