@salesforce/b2c-dx-mcp 2.0.0 → 2.1.1

package/dist/tools/storefrontnext/site-theming/index.js

@@ -1,128 +0,0 @@
-/*
- * 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
- */
-/**
- * Site Theming tool for Storefront Next.
- *
- * Provides theming guidelines, guided questions, and automatic WCAG color contrast
- * validation. Call this tool first when users request brand colors or theme changes.
- *
- * @module tools/storefrontnext/site-theming
- */
-import { z } from 'zod';
-import { createToolAdapter, textResult, errorResult } from '../../adapter.js';
-import { projectDirectoryInput } from '../../project-context.js';
-import { siteThemingStore } from './theming-store.js';
-import { mergeGuidance } from './guidance-merger.js';
-import { generateResponse } from './response-builder.js';
-/**
- * Creates the site theming MCP tool for Storefront Next.
- *
- * The tool guides theming changes (colors, fonts, visual styling) and validates color
- * combinations for WCAG accessibility. It must be called before implementing any
- * theming changes.
- *
- * @param loadServices - Function that loads configuration and returns Services instance
- * @returns The configured MCP tool
- */
-export function createSiteThemingTool(loadServices) {
-    return createToolAdapter({
-        name: 'sfnext_configure_theme',
-        description: '[DEPRECATED] Superseded by the storefront-next and storefront-next-figma agent-skills plugins and NOT compatible with the Storefront Next 1.0 GA release. Will be removed in a future release. ' +
-            '⚠️ MANDATORY: Call this tool FIRST before implementing any theming changes. ' +
-            'Provides theming guidelines, questions, and automatic validation. ' +
-            'CRITICAL RULES: Call immediately when user requests theming (even if colors/fonts provided). ' +
-            'NEVER implement without calling this tool first. NEVER skip question-answer workflow. ' +
-            'MUST ask questions and WAIT for responses. ' +
-            'VALIDATION GATE: After collecting answers, call tool again with colorMapping to trigger validation. ' +
-            'DEFAULT FILES: theming-questions, theming-validation, theming-accessibility. ' +
-            'Use fileKeys to add custom files. ' +
-            'WORKFLOW: Call tool → Ask questions → Call with colorMapping (validation) → Present findings → Wait confirmation → Implement',
-        toolsets: ['STOREFRONTNEXT_DEPRECATED'],
-        isGA: false,
-        requiresInstance: false,
-        usesProjectContext: true,
-        inputSchema: {
-            projectDirectory: projectDirectoryInput,
-            fileKeys: z
-                .array(z.string())
-                .optional()
-                .describe('Array of file keys to add to the default set. If provided, guidance from all specified files will be merged with defaults: theming-questions, theming-validation, theming-accessibility. Available keys can be listed by calling the tool without parameters.'),
-            conversationContext: z
-                .object({
-                currentStep: z
-                    .string()
-                    .optional()
-                    .describe('Current step in the theming conversation (e.g., "collecting-colors", "collecting-fonts")'),
-                collectedAnswers: z
-                    .record(z.string(), z.any())
-                    .optional()
-                    .describe('Previously collected answers from the user'),
-                questionsAsked: z.array(z.string()).optional().describe('List of questions that have already been asked'),
-            })
-                .optional()
-                .describe('Context from previous conversation rounds'),
-        },
-        async execute(args, context) {
-            siteThemingStore.initialize(context.services.resolveWithProjectDirectory(undefined, args.projectDirectory), {
-                themingFiles: context.services.getEnvironmentVariable('THEMING_FILES'),
-            });
-            const defaultFileKeys = ['theming-questions', 'theming-validation', 'theming-accessibility'];
-            let fileKeys;
-            if (args.fileKeys && args.fileKeys.length > 0) {
-                const allKeys = [...defaultFileKeys, ...args.fileKeys];
-                fileKeys = [...new Set(allKeys)];
-            }
-            else {
-                fileKeys = defaultFileKeys;
-            }
-            const hasContext = args.conversationContext &&
-                (args.conversationContext.collectedAnswers ||
-                    args.conversationContext.questionsAsked ||
-                    args.conversationContext.currentStep);
-            if (!args.fileKeys && !hasContext) {
-                const availableKeys = siteThemingStore.getKeys();
-                if (availableKeys.length === 0) {
-                    return {
-                        text: 'No theming files have been loaded. Please ensure theming files are configured at server startup.',
-                        isError: false,
-                    };
-                }
-                return {
-                    text: `Available theming files:\n\n${availableKeys.map((key) => `- ${key}`).join('\n')}\n\nDefault files (always used): theming-questions, theming-validation, theming-accessibility\n\nUse the \`fileKeys\` parameter to add additional files. User-provided files are merged with the defaults.`,
-                    isError: false,
-                };
-            }
-            const guidanceArray = [];
-            const missingKeys = [];
-            for (const key of fileKeys) {
-                const guidance = siteThemingStore.get(key);
-                if (guidance) {
-                    guidanceArray.push(guidance);
-                }
-                else {
-                    missingKeys.push(key);
-                }
-            }
-            if (guidanceArray.length === 0 || missingKeys.length > 0) {
-                const availableKeys = siteThemingStore.getKeys();
-                const keysList = fileKeys.length === 1 ? `key "${fileKeys[0]}"` : `keys: ${fileKeys.join(', ')}`;
-                const missingList = missingKeys.length === 1 ? `"${missingKeys[0]}"` : missingKeys.join(', ');
-                return {
-                    text: `Theming file(s) with ${keysList} not found.\n\nMissing: ${missingList}\nAvailable keys: ${availableKeys.join(', ')}\n\nFiles are loaded at server startup. To add more files, configure them via the THEMING_FILES environment variable or update the server initialization.`,
-                    isError: true,
-                };
-            }
-            const guidance = fileKeys.length > 1 ? mergeGuidance(guidanceArray) : guidanceArray[0];
-            const response = generateResponse(guidance, args.conversationContext);
-            return {
-                text: response,
-                isError: false,
-            };
-        },
-        formatOutput: (output) => output.isError ? errorResult(output.text) : textResult(output.text),
-    }, loadServices);
-}
-//# sourceMappingURL=index.js.map

package/dist/tools/storefrontnext/site-theming/response-builder.d.ts

@@ -1,16 +0,0 @@
-/**
- * Builds the theming tool response from guidance and conversation context.
- *
- * @module tools/storefrontnext/site-theming/response-builder
- */
-import type { ThemingGuidance } from './theming-store.js';
-import type { ConversationContext } from './types.js';
-/**
- * Returns questions relevant to the current conversation state, filtered and sorted.
- */
-export declare function getRelevantQuestions(guidance: ThemingGuidance, context?: ConversationContext): ThemingGuidance['questions'];
-export declare function hasProvidedThemingInfo(context?: ConversationContext): boolean;
-/**
- * Generates the full theming tool response from guidance and conversation context.
- */
-export declare function generateResponse(guidance: ThemingGuidance, context?: ConversationContext): string;

package/dist/tools/storefrontnext/site-theming/response-builder.js

@@ -1,316 +0,0 @@
-/*
- * 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
- */
-import { buildColorCombinations, appendValidationSection } from './color-mapping.js';
-function isComponentScopeQuestion(question) {
-    const questionLower = question.question.toLowerCase();
-    return (questionLower.includes('which components') ||
-        questionLower.includes('component scope') ||
-        questionLower.includes('component group'));
-}
-/**
- * Returns questions relevant to the current conversation state, filtered and sorted.
- */
-export function getRelevantQuestions(guidance, context) {
-    if (!context || !context.questionsAsked || context.questionsAsked.length === 0) {
-        return guidance.questions
-            .filter((q) => !isComponentScopeQuestion(q))
-            .sort((a, b) => {
-            if (a.required !== b.required) {
-                return a.required ? -1 : 1;
-            }
-            const categoryOrder = { colors: 0, typography: 1, general: 2 };
-            return ((categoryOrder[a.category] || 2) -
-                (categoryOrder[b.category] || 2));
-        });
-    }
-    const askedIds = new Set(context.questionsAsked);
-    const remaining = guidance.questions.filter((q) => !askedIds.has(q.id) && !isComponentScopeQuestion(q));
-    if (context.collectedAnswers) {
-        const followUps = [];
-        for (const q of remaining) {
-            if (q.followUpQuestions && context.collectedAnswers?.[q.id]) {
-                for (const [index, followUp] of q.followUpQuestions.entries()) {
-                    followUps.push({
-                        id: `${q.id}-followup-${index}`,
-                        question: followUp,
-                        category: q.category,
-                        required: false,
-                    });
-                }
-            }
-        }
-        return [...remaining, ...followUps];
-    }
-    return remaining;
-}
-export function hasProvidedThemingInfo(context) {
-    if (!context?.collectedAnswers) {
-        return false;
-    }
-    const collectedAnswers = context.collectedAnswers;
-    const hasColors = Boolean(collectedAnswers.colors && Array.isArray(collectedAnswers.colors));
-    const hasFonts = Boolean(collectedAnswers.fonts && Array.isArray(collectedAnswers.fonts));
-    return hasColors || hasFonts;
-}
-function buildExtractionResponse(extractionInstructions) {
-    const internal = '# ⚠️ MANDATORY: Extract User-Provided Theming Information\n\n## 🚨 CRITICAL: Information Extraction Required\n\n' +
-        extractionInstructions;
-    const user = "I need to extract the theming information from your input first.\n\nLet me review what you've shared and structure it properly, then I'll proceed with clarifying questions.\n\n";
-    return `${internal}\n\n---\n\n# USER-FACING RESPONSE (What to say to the user):\n\n${user}`;
-}
-function appendValidationInstructions(out, validation) {
-    let s = out +
-        '## ⚠️ MANDATORY: Input Validation\n\n**BEFORE implementing, you MUST validate ALL user-provided inputs:**\n\n';
-    if (validation.colorValidation)
-        s +=
-            '**A. Color Combination Validation (MANDATORY if colors provided):**\n\n' + validation.colorValidation + '\n\n';
-    if (validation.fontValidation)
-        s += '**B. Font Validation (MANDATORY if fonts provided):**\n\n' + validation.fontValidation + '\n\n';
-    if (validation.generalValidation)
-        s += '**C. General Input Validation:**\n\n' + validation.generalValidation + '\n\n';
-    if (validation.requirements)
-        s += '**IMPORTANT:**\n\n' + validation.requirements + '\n\n';
-    return s;
-}
-function appendCriticalAndRules(out, guidance) {
-    let s = out;
-    const critical = guidance.guidelines.filter((g) => g.critical);
-    if (critical.length > 0) {
-        s += '## ⚠️ Critical Guidelines (INTERNAL - Follow these rules)\n\n';
-        for (const g of critical)
-            s += `### ${g.title}\n\n${g.content}\n\n`;
-    }
-    if (guidance.rules.length > 0) {
-        s += '## Rules to Follow (INTERNAL)\n\n';
-        const doRules = guidance.rules.filter((r) => r.type === 'do');
-        const dontRules = guidance.rules.filter((r) => r.type === 'dont');
-        if (doRules.length > 0) {
-            s += '### ✅ What TO Do:\n\n';
-            for (const r of doRules)
-                s += `- ${r.description}\n`;
-            s += '\n';
-        }
-        if (dontRules.length > 0) {
-            s += '### ❌ What NOT to Do:\n\n';
-            for (const r of dontRules)
-                s += `- ${r.description}\n`;
-            s += '\n';
-        }
-    }
-    return s;
-}
-function extractColorsFromArray(colors) {
-    if (!colors || !Array.isArray(colors))
-        return [];
-    const out = [];
-    for (const color of colors) {
-        if (color.hex && color.type)
-            out.push(`${color.hex} (${color.type})`);
-        else if (color.hex)
-            out.push(color.hex);
-    }
-    return out;
-}
-function extractFontsFromArray(fonts) {
-    if (!fonts || !Array.isArray(fonts))
-        return [];
-    const out = [];
-    for (const font of fonts) {
-        if (font.name)
-            out.push(font.type ? `${font.name} (${font.type})` : font.name);
-    }
-    return out;
-}
-function extractColorFromValue(value) {
-    if (typeof value === 'string')
-        return value;
-    if (typeof value === 'object' && value && 'hex' in value) {
-        const v = value;
-        if (v.hex === undefined)
-            return null;
-        return v.type ? `${v.hex} (${v.type})` : v.hex;
-    }
-    return null;
-}
-function extractFontFromValue(value) {
-    if (typeof value === 'string')
-        return value;
-    if (typeof value === 'object' && value && 'name' in value) {
-        const v = value;
-        if (v.name === undefined)
-            return null;
-        return v.type ? `${v.name} (${v.type})` : v.name;
-    }
-    return null;
-}
-function shouldSkipKeyForOtherInfo(key, lowerKey) {
-    if (key === 'colors' || key === 'fonts')
-        return true;
-    if (lowerKey.includes('question') || lowerKey.includes('step'))
-        return true;
-    if (lowerKey.includes('color') || lowerKey.includes('font'))
-        return true;
-    return false;
-}
-function extractOtherInfoFromEntries(collectedAnswers) {
-    const otherInfo = [];
-    for (const key of Object.keys(collectedAnswers)) {
-        const lowerKey = key.toLowerCase();
-        if (shouldSkipKeyForOtherInfo(key, lowerKey))
-            continue;
-        const value = collectedAnswers[key];
-        if (value === null || value === undefined)
-            continue;
-        otherInfo.push(`${key}: ${typeof value === 'object' ? JSON.stringify(value) : value}`);
-    }
-    return otherInfo;
-}
-function collectUserInfo(collectedAnswers) {
-    const colorsInfo = [...extractColorsFromArray(collectedAnswers.colors)];
-    const fontsInfo = [...extractFontsFromArray(collectedAnswers.fonts)];
-    for (const key of Object.keys(collectedAnswers)) {
-        const lowerKey = key.toLowerCase();
-        const value = collectedAnswers[key];
-        if (key === 'colors' || key === 'fonts' || lowerKey.includes('question') || lowerKey.includes('step'))
-            continue;
-        if (lowerKey.includes('color') && !key.includes('colors')) {
-            const c = extractColorFromValue(value);
-            if (c)
-                colorsInfo.push(c);
-            continue;
-        }
-        if (lowerKey.includes('font') && !key.includes('fonts')) {
-            const f = extractFontFromValue(value);
-            if (f)
-                fontsInfo.push(f);
-            continue;
-        }
-    }
-    const otherInfo = extractOtherInfoFromEntries(collectedAnswers);
-    return { colorsInfo, fontsInfo, otherInfo };
-}
-function buildUserInfoSection(info) {
-    const { colorsInfo, fontsInfo, otherInfo } = info;
-    if (colorsInfo.length === 0 && fontsInfo.length === 0 && otherInfo.length === 0) {
-        return 'Following the theming workflow. I need a few clarifications before implementing.\n\n';
-    }
-    let s = "## Information You've Provided\n\n";
-    if (colorsInfo.length > 0) {
-        s += '### Colors:\n';
-        for (const c of colorsInfo)
-            s += `- ${c}\n`;
-        s += '\n';
-    }
-    if (fontsInfo.length > 0) {
-        s += '### Fonts:\n';
-        for (const f of fontsInfo)
-            s += `- ${f}\n`;
-        s += '\n';
-    }
-    if (otherInfo.length > 0) {
-        s += '### Other Information:\n';
-        for (const o of otherInfo)
-            s += `- ${o}\n`;
-        s += '\n';
-    }
-    return (s +
-        "I've noted the information above. Before implementing, I need a few clarifications to ensure everything is set up correctly.\n\n");
-}
-function buildInternalInstructionsBase(guidance, context) {
-    let s = '# ⚠️ MANDATORY: Site Theming Guidelines and Questions\n\n## 🚨 CRITICAL: Read This First\n\n';
-    if (guidance.workflow?.steps && guidance.workflow.steps.length > 0) {
-        s += '**YOU MUST FOLLOW THIS WORKFLOW - NO EXCEPTIONS:**\n\n';
-        for (const [i, step] of guidance.workflow.steps.entries())
-            s += `${i + 1}. ${step}\n`;
-        s += '\n**VIOLATION OF THIS WORKFLOW IS A CRITICAL ERROR.**\n\n';
-    }
-    if (guidance.validation)
-        s = appendValidationInstructions(s, guidance.validation);
-    const colorMapping = context?.collectedAnswers?.colorMapping;
-    if (colorMapping && Object.keys(colorMapping).length > 0) {
-        s +=
-            '## 🎨 AUTOMATED COLOR VALIDATION RESULTS\n\n**The following validation has been automatically performed using built-in contrast calculation:**\n\n';
-        s = appendValidationSection(s, buildColorCombinations(colorMapping));
-    }
-    return appendCriticalAndRules(s, guidance);
-}
-function appendQuestionsToResponse(internal, user, nextQuestions, relevantQuestions) {
-    let userOut = user + '## Questions\n\n';
-    const categories = [
-        { category: 'colors', title: 'Color Questions' },
-        { category: 'typography', title: 'Font Questions' },
-        { category: 'general', title: 'General Questions' },
-    ];
-    for (const { category, title } of categories) {
-        const qs = nextQuestions.filter((q) => q.category === category);
-        if (qs.length > 0) {
-            userOut += `### ${title}\n\n`;
-            for (const [i, q] of qs.entries())
-                userOut += `**Question ${i + 1}**: ${q.question}\n\n`;
-        }
-    }
-    const remaining = relevantQuestions.length - nextQuestions.length;
-    if (remaining > 0)
-        userOut += `\n_Note: I have ${remaining} more question${remaining > 1 ? 's' : ''} to ask after you answer these._\n\n`;
-    userOut += 'Please answer these questions so I can proceed with the implementation.\n\n';
-    let internalOut = internal +
-        "## Questions to Ask the User\n\n**IMPORTANT**: Ask these questions ONE AT A TIME and WAIT for the user's response before proceeding.\n\n**CRITICAL RULE**: NEVER implement changes after asking questions without waiting for the user's response.\n\n";
-    internalOut += `**You have ${relevantQuestions.length} total questions to ask. Show ${nextQuestions.length} now, then continue with the rest after user responds.**\n\n`;
-    for (const [i, q] of nextQuestions.entries()) {
-        internalOut += `### Question ${i + 1} (${q.category}): ${q.id}\n\n${q.question}\n\n`;
-        if (q.required)
-            internalOut += '**Required**: Yes\n\n';
-    }
-    return { internal: internalOut, user: userOut };
-}
-function appendReadyOrWarningToResponse(internal, user, guidance, context) {
-    const required = guidance.questions.filter((q) => q.required);
-    const answered = required.filter((q) => context.collectedAnswers?.[q.id] !== undefined);
-    if (answered.length < required.length) {
-        return {
-            internal: internal +
-                '## ⚠️ WARNING: Not all required questions have been answered!\n\n**DO NOT implement yet. Continue asking questions.**\n\n',
-            user: user + 'I still need answers to some required questions before I can proceed.\n\n',
-        };
-    }
-    let internalOut = internal;
-    if (guidance.workflow?.preImplementationChecklist) {
-        internalOut +=
-            '## ⚠️ MANDATORY PRE-IMPLEMENTATION CHECKLIST\n\n' + guidance.workflow.preImplementationChecklist + '\n\n';
-    }
-    const userOut = user +
-        '## Ready to Implement\n\nI have collected all necessary information. Before implementing, I will validate all provided inputs (colors, fonts, etc.) for accessibility, availability, and best practices.\n\n';
-    return { internal: internalOut, user: userOut };
-}
-/**
- * Generates the full theming tool response from guidance and conversation context.
- */
-export function generateResponse(guidance, context) {
-    const isFirstCall = !context || !context.questionsAsked || context.questionsAsked.length === 0;
-    if (isFirstCall && !hasProvidedThemingInfo(context) && guidance.workflow?.extractionInstructions) {
-        return buildExtractionResponse(guidance.workflow.extractionInstructions);
-    }
-    const relevantQuestions = getRelevantQuestions(guidance, context);
-    const questionLimit = !context || context.questionsAsked?.length === 0 ? 5 : 3;
-    const nextQuestions = relevantQuestions.slice(0, questionLimit);
-    let internalInstructions = buildInternalInstructionsBase(guidance, context);
-    const info = context?.collectedAnswers
-        ? collectUserInfo(context.collectedAnswers)
-        : { colorsInfo: [], fontsInfo: [], otherInfo: [] };
-    let userResponse = buildUserInfoSection(info);
-    if (nextQuestions.length > 0) {
-        const appended = appendQuestionsToResponse(internalInstructions, userResponse, nextQuestions, relevantQuestions);
-        internalInstructions = appended.internal;
-        userResponse = appended.user;
-    }
-    else if (context?.collectedAnswers && Object.keys(context.collectedAnswers).length > 0) {
-        const appended = appendReadyOrWarningToResponse(internalInstructions, userResponse, guidance, context);
-        internalInstructions = appended.internal;
-        userResponse = appended.user;
-    }
-    return `${internalInstructions}\n\n---\n\n# USER-FACING RESPONSE (What to say to the user):\n\n${userResponse}`;
-}
-//# sourceMappingURL=response-builder.js.map

package/dist/tools/storefrontnext/site-theming/theming-store.d.ts

@@ -1,64 +0,0 @@
-export interface ThemingGuidance {
-    questions: Array<{
-        id: string;
-        question: string;
-        category: string;
-        required: boolean;
-        followUpQuestions?: string[];
-    }>;
-    guidelines: Array<{
-        category: string;
-        title: string;
-        content: string;
-        critical: boolean;
-    }>;
-    rules: Array<{
-        type: 'do' | 'dont';
-        description: string;
-        examples?: string[];
-    }>;
-    workflow?: {
-        steps: string[];
-        extractionInstructions?: string;
-        preImplementationChecklist?: string;
-    };
-    validation?: {
-        colorValidation?: string;
-        fontValidation?: string;
-        generalValidation?: string;
-        requirements?: string;
-    };
-    metadata: {
-        filePath: string;
-        fileName: string;
-        loadedAt: Date;
-    };
-}
-/**
- * Theming Data Store
- * Loads and caches theming guidance from .md/.mdc files
- */
-export interface InitializeOptions {
-    /** Override content directory for default files (used in tests). */
-    contentDirOverride?: string;
-    /** Project-scoped THEMING_FILES value. */
-    themingFiles?: string;
-}
-declare class ThemingStore {
-    private initializedForRoot;
-    private store;
-    get(fileKey: string): ThemingGuidance | undefined;
-    getKeys(): string[];
-    has(fileKey: string): boolean;
-    /**
-     * Initialize store with default files from content/site-theming.
-     * Uses workspaceRoot for THEMING_FILES env paths (relative to project).
-     * Skips re-loading when already initialized for the same root.
-     */
-    initialize(workspaceRoot?: string, options?: InitializeOptions): void;
-    loadFile(fileKey: string, filePath: string): void;
-    private loadThemingFilesFromEnv;
-    private tryLoadEnvFile;
-}
-export declare const siteThemingStore: ThemingStore;
-export {};