Merge pull request #2794 from SalesforceCommerceCloud/bendvc/revert-create-app-changes

[🧱 MCP Server Tool] Create App Tool Polish 💅

Author: bendvc

packages/pwa-kit-create-app/program.json

@@ -1,4 +1,8 @@
 {
+    "_ai": {
+        "instruction": "This file defines the CLI behavior for generating React projects using templates and presets. AI agents can use this to guide interactive or programmatic project creation.",
+        "expectedUse": "Provides schema and data for decision making during app generation."
+    },
     "$schema": "http://json-schema.org/draft-07/schema#",
     "metadata": {
         "name": "pwa-kit-create-app",
@@ -22,13 +26,21 @@
                 ],
                 "properties": {
                     "name": {
-                        "type": "string"
+                        "type": "string",
+                        "_ai": {
+                            "instruction": "This value maps directly to the key in the answers object.",
+                            "expectedUse": "Use this to store or retrieve the corresponding answer."
+                        }
                     },
                     "message": {
                         "type": "string"
                     },
                     "type": {
-                        "type": "string"
+                        "type": "string",
+                        "_ai": {
+                            "instruction": "This defines the prompt type (e.g., list, input, confirm). Determines how to display the question.",
+                            "expectedUse": "Configure the appropriate UI for asking the question."
+                        }
                     },
                     "choices": {
                         "type": "array",
@@ -44,10 +56,18 @@
                                 },
                                 "value": {}
                             }
+                        },
+                        "_ai": {
+                            "instruction": "Only used when type is 'list', 'rawlist', 'checkbox', or similar. These are the selectable options.",
+                            "expectedUse": "Render multiple choice options to the user."
                         }
                     }
                 },
                 "additionalProperties": true
+            },
+            "_ai": {
+                "instruction": "Defines the questions to be asked to the user or AI agent to gather required input for project generation.",
+                "expectedUse": "Used to drive interactive or programmatic question-and-answer flows."
             }
         },
         "presets": {
@@ -80,12 +100,16 @@
                     },
                     "answers": {
                         "type": "object",
-                        "additionalProperties": {}
+                        "additionalProperties": {},
+                        "_ai": {
+                            "instruction": "These are default answers pre-filled when this preset is selected. They should be merged with user-supplied answers, where user-supplied values take precedence.",
+                            "expectedUse": "Auto-filling answers to questions without prompting the user unless a value is missing or overridden."
+                        }
                     },
                     "private": {
                         "type": "boolean",
                         "_ai": {
-                            "instruction": "This property is used to filter what presets are shown to the user. If the preset is private, should NOT be shown to the user in a list of selectable presets. This equates to the 'when' property Inquirer question schema.",
+                            "instruction": "This property is used to filter what presets are shown to the user. If the preset is private, it should NOT be shown to the user in a list of selectable presets.",
                             "expectedUse": "Hiding presets from the user."
                         }
                     }
@@ -142,7 +166,11 @@
                         },
                         "required": [
                             "type"
-                        ]
+                        ],
+                        "_ai": {
+                            "instruction": "This defines how the template is sourced. If 'npm', then 'name' must be the NPM package name. If 'bundle', the template is included directly in the CLI.",
+                            "expectedUse": "Used to determine how to fetch and prepare the template for project creation."
+                        }
                     },
                     "questions": {
                         "$ref": "questions.json",
@@ -159,7 +187,11 @@
                     },
                     "answers": {
                         "type": "object",
-                        "additionalProperties": {}
+                        "additionalProperties": {},
+                        "_ai": {
+                            "instruction": "These are default answers pre-filled when this template is selected. They should be merged with user-supplied answers, where user-supplied values take precedence.",
+                            "expectedUse": "Auto-filling answers to questions without prompting the user unless a value is missing or overridden."
+                        }
                     },
                     "private": {
                         "type": "boolean",
@@ -217,6 +249,10 @@
                     "message",
                     "regex"
                 ]
+            },
+            "_ai": {
+                "instruction": "These validators can be applied to template questions to ensure valid input. Each validator has a unique `id` that is referenced from questions.",
+                "expectedUse": "Validating user input for questions during project creation."
             }
         },
         "options": {
@@ -237,7 +273,15 @@
                 "required": [
                     "name",
                     "description"
-                ]
+                ],
+                "_ai": {
+                    "instruction": "This option modifies the behavior of the CLI tool. Use `defaultValue` if the option is not provided.",
+                    "expectedUse": "Determine which CLI flags can be included when generating the command."
+                }
+            },
+            "_ai": {
+                "instruction": "These are the options/arguments that can be passed to the @salesforce/pwa-kit-create-app CLI tool. Do not use options that aren't listed here.",
+                "expectedUse": "Instruct agent on how to use the @salesforce/pwa-kit-create-app CLI tool to create a new PWA Kit project."
             }
         },
         "examples": {
@@ -255,7 +299,11 @@
                 "required": [
                     "description",
                     "command"
-                ]
+                ],
+                "_ai": {
+                    "instruction": "Each example shows how to use the CLI tool with real command-line input.",
+                    "expectedUse": "Show examples in documentation or when the agent is generating usage examples."
+                }
             }
         }
     },
@@ -692,4 +740,4 @@
             }
         ]
     }
-}
+}

packages/pwa-storefront-mcp/jest.config.js

@@ -6,12 +6,15 @@
  */
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const parentConfig = require('@salesforce/pwa-kit-dev/configs/jest/jest.config.js')
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const path = require('path')
 
 module.exports = {
     ...parentConfig,
     testEnvironment: 'node',
     testMatch: ['**/__tests__/**/*.js', '**/?(*.)+(spec|test).js'],
     testPathIgnorePatterns: ['bin/*', 'coverage/*', 'dist/*', 'node_modules/*', 'scripts/*'],
+    setupFilesAfterEnv: [path.join(__dirname, 'jest-setup.js')],
     collectCoverageFrom: ['src/**/*.js', '!src/**/*.test.js', '!src/**/*.spec.js'],
     coverageDirectory: 'coverage',
     coverageReporters: ['text', 'lcov', 'html'],

packages/pwa-storefront-mcp/package-lock.json

@@ -95,7 +95,7 @@ class PwaStorefrontMCPServerHighLevel {
             this.sessions[sessionId] = {step: 1, answers: {}}
         }
         const session = this.sessions[sessionId]
-        const {step, answers} = session
+        const {step} = session
         const answer = args.answer?.trim()
         switch (step) {
             case 1:

packages/pwa-storefront-mcp/src/server/server.js

@@ -37,7 +37,12 @@ describe('PwaStorefrontMCPServerHighLevel integration', () => {
     it('should list registered tools via stdio', async () => {
         const child = spawn(BABEL_NODE_PATH, ['src/server/server.js'], {
             cwd: process.cwd(),
-            stdio: ['pipe', 'pipe', 'inherit']
+            stdio: ['pipe', 'pipe', 'inherit'],
+            env: {
+                ...process.env,
+                // NOTE: THIS ENV VAR IS  USUALLY SET BY CURSOR OR THE MCP SERVER?
+                WORKSPACE_FOLDER_PATHS: path.resolve(process.cwd(), '..', '..')
+            }
         })
 
         // Wait a moment for the server to start

packages/pwa-storefront-mcp/src/server/server.test.js

@@ -139,7 +139,6 @@ export default ${pascalComponentName};
         const componentDir = path.join(location, kebabDirName)
         await fs.mkdir(componentDir, {recursive: true})
         const componentFilePath = path.join(componentDir, 'index.jsx')
-        const fields = Object.keys(dataModel)
         let code = ''
 
         // Special logic for product entity

packages/pwa-storefront-mcp/src/utils/create-new-component-tool.js

@@ -6,7 +6,6 @@
  */
 import CreateNewComponentTool from './create-new-component-tool.js'
 import * as fs from 'fs/promises'
-import path from 'path'
 
 // Mock fs/promises to avoid actual file operations
 jest.mock('fs/promises', () => ({

packages/pwa-storefront-mcp/src/utils/create-new-component-tool.test.js

@@ -4,19 +4,13 @@
  * SPDX-License-Identifier: BSD-3-Clause
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
-import os from 'os'
-import path from 'path'
-import {exec} from 'child_process'
-import fs from 'fs/promises'
 
 // Project dependencies
-import {EmptyJsonSchema, runNpxCommand} from './utils'
+import {EmptyJsonSchema, getCreateAppCommand, isMonoRepo, runCommand} from './utils'
 
-//const CREATE_APP_VERSION = 'latest'
-//const CREATE_APP_VERSION = '3.11.0-nightly-20250630080227'
-const CREATE_APP_COMMAND = '@salesforce/pwa-kit-create-app@3.11.0-nightly-20250630080227'
-const DISPLAY_PROGRAM_COMMAND = '--displayProgram'
-const NPX_COMMAND = 'npx'
+const CREATE_APP_COMMAND = getCreateAppCommand()
+const DISPLAY_PROGRAM_FLAG = '--displayProgram'
+const COMMAND_RUNNER = isMonoRepo() ? 'node' : 'npx'
 
 const guidelinesText = `
 # PWA Kit Create App — Agent Usage Guidelines
@@ -63,26 +57,21 @@ If the user requests a project using a **template**:
 - Never attempt to create a project without using this tool.
 - When gathering answers for a template, ask questions one at a time to maintain clarity.
 - Presets and templates are mutually exclusive paths. Do not offer both options unless explicitly requested.
-- Use the \`${NPX_COMMAND}\` command to run the \`${CREATE_APP_COMMAND}\` CLI tool when creating a new project.
+- Do not pass any flags to the \`${CREATE_APP_COMMAND}\` CLI tool that are not listed in the program.json options".
+- Use the \`${COMMAND_RUNNER}\` command to run the \`${CREATE_APP_COMMAND}\` CLI tool when creating a new project.
 `
 
 export default {
     name: 'create_app_guidelines',
     description: `This tool is used to provide the agent with the instructions on how to use the @salesforce/pwa-kit-create-app CLI tool to create a new PWA Kit projects. Do not attempt to create a project without using this tool first.`,
     inputSchema: EmptyJsonSchema,
     fn: async () => {
-        let programOutput = ''
-
         // Run the display program and get the output.
-        try {
-            programOutput = await runNpxCommand(
-                NPX_COMMAND,
-                CREATE_APP_COMMAND,
-                DISPLAY_PROGRAM_COMMAND
-            )
-        } catch (err) {
-            console.error('Failed to run display program:', err)
-        }
+        const programOutput = await runCommand(COMMAND_RUNNER, [
+            ...(COMMAND_RUNNER === 'npx' ? ['--yes'] : []),
+            CREATE_APP_COMMAND,
+            DISPLAY_PROGRAM_FLAG
+        ])
 
         // Parse the output and get the data, metadata, and schemas.
         const {

packages/pwa-storefront-mcp/src/utils/pwa-create-app-guideline-tool.js

@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+import CreateAppGuidelineTool from './pwa-create-app-guideline-tool'
+import {EmptyJsonSchema} from './utils'
+
+jest.mock('./utils', () => {
+    const originalModule = jest.requireActual('./utils')
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const path = require('path')
+    const mockScriptPath = path.resolve('../pwa-kit-create-app/scripts/create-mobify-app.js')
+
+    return {
+        ...originalModule,
+        isMonoRepo: jest.fn(() => true),
+        getCreateAppCommand: jest.fn(() => mockScriptPath)
+    }
+})
+
+describe('PWA Create App Guidelines', () => {
+    describe('CreateAppGuidelineTool', () => {
+        it('should have correct structure', () => {
+            expect(CreateAppGuidelineTool).toMatchObject({
+                name: 'create_app_guidelines',
+                description: `This tool is used to provide the agent with the instructions on how to use the @salesforce/pwa-kit-create-app CLI tool to create a new PWA Kit projects. Do not attempt to create a project without using this tool first.`,
+                inputSchema: EmptyJsonSchema,
+                fn: expect.any(Function)
+            })
+        })
+
+        it('should return guidelines content when executed', async () => {
+            // NOTE: THIS TEST IS SIMPLY A SANITY CHECK TO ENSURE THE TOOL IS WORKING.
+            // IT DOES NOT TEST THE CONTENT OF THE GUIDELINES IN ITS ENTIRETY.
+            const result = await CreateAppGuidelineTool.fn()
+
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: expect.stringContaining('PWA Kit Create App — Agent Usage Guidelines')
+                    }
+                ]
+            })
+        })
+
+        it('should include all major sections in the guidelines', async () => {
+            const result = await CreateAppGuidelineTool.fn()
+            const guidelineText = result.content[0].text
+
+            const requiredSections = [
+                'Overview',
+                'General Rules',
+                'Creating a Project Using a Preset',
+                'Creating a Project Using a Template',
+                'Important Reminders'
+            ]
+
+            requiredSections.forEach((section) => {
+                expect(guidelineText).toContain(section)
+            })
+        })
+    })
+})
+
+afterAll(() => {
+    delete process.env.WORKSPACE_FOLDER_PATHS
+})