Add `program.json` + Support for Agent-Friendly CLI Input via stdio @@W-18855311@@ by bendvc · Pull Request #2662 · SalesforceCommerceCloud/pwa-kit

bendvc · 2025-06-26T17:29:33Z

Description

This PR introduces several improvements to the create-mobify-app script that make it easier to automate and integrate with AI agents or other tooling. Key updates include:

Introduced program.json: A new JSON-based manifest that defines the behavior and structure of the CLI tool. This serves as a machine-readable contract for tools like the MCP server.
Added support for stdio input: Enables passing answers via stdin, allowing agents to gather and pipe input directly into the CLI—great for non-interactive environments and automation.
Refactored internal CLI logic to read from program.json, making the tool’s structure more declarative and extensible.
Updated data structures and templates to align with this new configuration-driven model.
Added --displayProgram argument: A new script action to display the schemas and data that this script uses, we ingest this from out MCP server.

These changes pave the way for more flexible, agent-driven CLI workflows while keeping the experience familiar for human users.

Types of Changes

How to Test-Drive This PR

Pull the branch and run the CLI tool manually to ensure the prompts still behave as expected.

Pipe a JSON payload of answers into the CLI via stdin to verify agent-style automation works:

echo '{"project.extend":true,"project.name":"demo-storefront","project.commerce.instanceUrl":"https://zzte-053.dx.commercecloud.salesforce.com","project.commerce.clientId":"1d763261-6522-4913-9d52-5d947d3b94c4","project.commerce.isSlasPrivate":false,"project.commerce.siteId":"RefArch","project.commerce.organizationId":"f_ecom_zzte_053","project.commerce.shortCode":"kv7kzm78","general.presetOrTemplateId":"retail-react-app"}' | node ./scripts/create-mobify-app --stdio

Check that updates to the generated app files (e.g., templates) reflect the expected changes.
Review program.json and confirm it correctly describes available questions and options.

Checklists

General

Changes are covered by test cases
CHANGELOG.md updated with a short description of changes

Accessibility Compliance

There are no changes to UI

- Create `program.json` to define project operation (this is consumed by the MCP server) - Allow stdio input for answers. This allows integration with agents where they can gather answers and pipe them to the cli for project generation. - Updates to data structure and asset templates. - Use program.json in the script to configure the internal commander app

cc-prodsec · 2025-06-26T17:29:44Z

🎉 Snyk checks have passed. No issues have been found so far.

✅ security/snyk check is complete. No issues have been found. (View Details)

✅ license/snyk check is complete. No issues have been found. (View Details)

Tried to use the package name as the template id, but this doesn't work with a lot of our current logic. So I reverted it.

vmarta · 2025-06-27T00:19:01Z

packages/pwa-kit-create-app/scripts/create-mobify-app.js

+        // NOTE: This is a little weird, but we'll set this value to the template id and treat is as such from this point forward..
+        answers.general.presetOrTemplateId = selectedPreset.templateId


There are a few comments in this file where you said this may be weird.. how about merging both presets and templates into a single list?

AI shows what that could look like:

const ALL_TEMPLATES = [ // Convert presets to templates with default answers ...RAW_PRESETS.map((preset) => { const baseTemplate = RAW_TEMPLATES.find((t) => t.id === preset.templateId) if (!baseTemplate) { throw new Error( `Preset "${preset.id}" references unknown template "${preset.templateId}"` ) } return { ...baseTemplate, // Template structure (questions, assets, etc.) id: preset.id, // Use preset ID as the unified ID name: preset.name, // Use preset name description: preset.description, shortDescription: preset.shortDescription, isPreset: true, // Flag to identify presets templateId: preset.templateId, // Keep reference to base template defaultAnswers: preset.answers, // Pre-filled answers private: preset.private } }), // Regular templates (no default answers) ...RAW_TEMPLATES.map((template) => ({ ...template, isPreset: false, templateId: template.id, // Template references itself defaultAnswers: {} // No pre-filled answers })) ]

Here's the full file: https://gist.github.com/vmarta/2273ea2dd094f1fab1df4f6eafe9ac82

I see there they are going with this, but I'm not sure it is in fact any less weird. I say that because this notion of "defaultAnswers". Initially if you had no idea about presets you would say that defaultAnswers would be used to show the user what the answer would be if they skipped the input or maybe use it as an example, but it would still ask you the question.

But I'm assuming what we would have to do here is say, if the template is actually a preset, then when we ask the questions, use the defaultAnswers as provided answers so they won't get asked in the first place.

And at first glance having a prop on a template called isPreset is still kinda weird, that data structure probably isn't a template but we use a variable called all_templates which serves to make us believe we are working with all templates.

How strongly do you feel about making this logic perfect before merging?

Related to change in the schema for the template

adamraya · 2025-06-27T18:21:34Z

packages/pwa-kit-create-app/scripts/create-mobify-app.js

+        try {
+            const input = await readStdin()
+            answers = merge(answers, expandObject(JSON.parse(input)))
+        } catch (err) {
+            console.error('Failed to read from stdin:', err.message)
+            process.exit(1)
+        }


Should we split the code into separate steps to let users know which step fails by providing more specific error messages?

Also, should we check if the input includes all required fields?

Something like:

try { const input = await readStdin() if (!input.trim()) { throw new Error('No input received. Please pipe valid JSON to stdin.') } const parsedInput = JSON.parse(input) if (!parsedInput['general.presetOrTemplateId']) { throw new Error('Missing required field: "general.presetOrTemplateId"') } answers = merge(answers, expandObject(parsedInput)) } catch (err) { if (err instanceof SyntaxError) { console.error('Invalid JSON format in stdin input') } else { console.error('Failed to process stdin input:', err.message) } process.exit(1) }

Thats a good called out. I can organize the code a little bit more to better show errors. But I'm not too sure about the answer validation in it's entirety... Maybe we can go with what you have here and validate that there is a presetORTemplateId.. the other answers are template specific and maybe we can create a follow up ticket to implement the stdio input better.

adamraya · 2025-06-27T18:42:14Z

packages/pwa-kit-create-app/scripts/create-mobify-app.js

+                ? (input) => new RegExp(validator.regex, 'i').test(input) || validator.message
+                : undefined


Should we catch errors in case the validator.regex is invalid?

In the future I think there will be a schema validation step that could be used to do something like this. Right now this is all a design time and if there is an error it's because the pwa-kit developer added something wrong to the program json and it's not something that would effect external developers that are using the script.

adamraya · 2025-06-27T18:50:45Z

packages/pwa-kit-create-app/scripts/create-mobify-app.js

    }

    // Extract the source
+    console.log('Extracting base template from package or npm: ', tarPath)


Are we intentionally leaving this console.log? Should we print this behind a verbose or debug flag?

No. Thanks for spotting that. I have removed it.

vmarta

A minor comment.. other than that, PR looks good to me 👍

vmarta · 2025-06-27T21:05:08Z

packages/pwa-kit-create-app/scripts/create-mobify-app.js

+ * @param {Object} answers - The current answers object to merge into.
+ * @returns {Promise<Object>} - The merged answers object.
+ */
+const getAnswersFromStdin = async (answers) => {


Minor: I feel the function name doesn't imply that there's going to be a merging of the initial answers and the ones from stdin. So when I see line 518 answers = await getAnswersFromStdin(answers), it made me think why we need to pass in answers.

How about doing the answers merging outside of this function? The error handling is focusing on json and stdin anyways, so it looks to me like the merging can be done outside.

adamraya · 2025-06-27T21:08:42Z

packages/pwa-kit-create-app/scripts/create-mobify-app.js

+    } catch (err) {
+        console.error('Failed to import program.json:', err.message)
+    }
+    process.exit(1)


Why are we using process.exit(1) for a successful operation? Should we use process.exit(0) instead? Or move it inside the catch block?

0 is success from what the ide is telling me.

adamraya · 2025-06-27T21:12:38Z

packages/pwa-kit-create-app/scripts/create-mobify-app.js

    const OUTPUT_DIR_FLAG_ACTIVE = !!outputDir
    const presetId = preset || process.env.GENERATOR_PRESET

+    // Exit if the preset provided is not valid.


nit: Is this comment copied and pasted? Should it instead say something like: "Display program schema and exit if requested"?

bendvc requested a review from a team as a code owner June 26, 2025 17:29

bendvc added the skip changelog Skip the "Changelog Check" GitHub Actions step even if the Changelog.md files are not updated label Jun 26, 2025

Update CHANGELOG.md

e34cbaf

bendvc requested review from adamraya and vmarta June 26, 2025 17:30

bendvc mentioned this pull request Jun 26, 2025

[𝍋 MCP Server Tool] Add pwa-kit-create-app guideline tool @@W-18812373@@ #2663

Merged

9 tasks

bendvc added 3 commits June 26, 2025 11:00

Ensure we include program.json

3a5d823

Update validation for url

b1d1ecd

Fix regression

0c302de

Tried to use the package name as the template id, but this doesn't work with a lot of our current logic. So I reverted it.

vmarta reviewed Jun 27, 2025

View reviewed changes

bendvc added 3 commits June 27, 2025 10:28

Fix npm view command

5d2b3bc

More small fixes

b9730c2

Related to change in the schema for the template

Fix more template references

93eddf8

adamraya reviewed Jun 27, 2025

View reviewed changes

PR feedback

dd9a66b

adamraya reviewed Jun 27, 2025

View reviewed changes

Print program data to be consumed by the mcp server or other ai

f22af3c

adamraya reviewed Jun 27, 2025

View reviewed changes

Remove debug log

9d63da5

vmarta previously approved these changes Jun 27, 2025

View reviewed changes

adamraya reviewed Jun 27, 2025

View reviewed changes

adamraya previously approved these changes Jun 27, 2025

View reviewed changes

PR feedback

9df1e94

bendvc dismissed stale reviews from adamraya and vmarta via 9df1e94 June 27, 2025 21:22

adamraya previously approved these changes Jun 27, 2025

View reviewed changes

vmarta previously approved these changes Jun 27, 2025

View reviewed changes

Fix AI code

b1c0f39

bendvc dismissed stale reviews from vmarta and adamraya via b1c0f39 June 27, 2025 21:37

vmarta approved these changes Jun 27, 2025

View reviewed changes

adamraya approved these changes Jun 27, 2025

View reviewed changes

bendvc merged commit 9e0adf8 into develop Jun 27, 2025
66 of 67 checks passed

bendvc deleted the bendvc/W-18855311_create-app-stdio branch June 27, 2025 22:11

vmarta mentioned this pull request Jul 7, 2025

[Generator] Copying template files is now successful (@W-18982846@) #2751

Merged

This was referenced Jul 14, 2025

@W-18794728: change demo instance, use a pod instead of sandbox #2610

Merged

Fix demo instance #2800

Merged

		// NOTE: This is a little weird, but we'll set this value to the template id and treat is as such from this point forward..
		answers.general.presetOrTemplateId = selectedPreset.templateId

		? (input) => new RegExp(validator.regex, 'i').test(input) \|\| validator.message
		: undefined

Conversation

bendvc commented Jun 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Types of Changes

How to Test-Drive This PR

Checklists

General

Accessibility Compliance

Uh oh!

cc-prodsec commented Jun 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎉 Snyk checks have passed. No issues have been found so far.

Uh oh!

vmarta Jun 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamraya Jun 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vmarta left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamraya Jun 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

bendvc commented Jun 26, 2025 •

edited

Loading

cc-prodsec commented Jun 26, 2025 •

edited

Loading

vmarta Jun 27, 2025 •

edited

Loading

adamraya Jun 27, 2025 •

edited

Loading

adamraya Jun 27, 2025 •

edited

Loading