@salesforce/b2c-dx-mcp 0.4.3 → 0.4.5

package/dist/tools/storefrontnext/site-theming/color-contrast.js

@@ -0,0 +1,186 @@
+/*
+ * 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
+ */
+/**
+ * WCAG 2.1 color contrast utilities for accessibility validation.
+ *
+ * Provides luminance calculation, contrast ratio computation, and WCAG compliance
+ * checking for theming and color validation in Storefront Next.
+ *
+ * @module tools/storefrontnext/site-theming/color-contrast
+ */
+/**
+ * WCAG 2.1 constants for contrast ratio calculation
+ * These values are specified in the WCAG 2.1 standard
+ */
+const WCAG_CONTRAST_OFFSET = 0.05; // Offset added to luminance values in contrast ratio formula
+// Linear RGB conversion constants (sRGB to linear RGB)
+const LINEAR_RGB_THRESHOLD = 0.039_28; // Threshold for linear RGB conversion
+const LINEAR_RGB_DIVISOR = 12.92; // Divisor for values below threshold
+const GAMMA_CORRECTION_OFFSET = 0.055; // Offset for gamma correction
+const GAMMA_CORRECTION_DIVISOR = 1.055; // Divisor for gamma correction
+const GAMMA_EXPONENT = 2.4; // Gamma exponent for sRGB
+// Relative luminance weights (WCAG 2.1 standard)
+const LUMINANCE_RED_WEIGHT = 0.2126;
+const LUMINANCE_GREEN_WEIGHT = 0.7152;
+const LUMINANCE_BLUE_WEIGHT = 0.0722;
+/** Valid 6-digit hex color pattern (with optional # prefix) */
+const HEX_PATTERN = /^#?[0-9A-Fa-f]{6}$/;
+/**
+ * Validates that a string is a valid 6-digit hex color.
+ * @param hex - Hex color string to validate
+ * @returns true if valid
+ */
+export function isValidHex(hex) {
+    return typeof hex === 'string' && HEX_PATTERN.test(hex.trim());
+}
+/**
+ * Calculates the relative luminance of a color according to WCAG 2.1
+ * @param hex - Hex color string (e.g., "#635BFF")
+ * @returns Relative luminance value between 0 and 1
+ * @throws Error if hex format is invalid
+ */
+export function getLuminance(hex) {
+    const trimmed = hex.trim();
+    if (!HEX_PATTERN.test(trimmed)) {
+        throw new Error(`Invalid hex color: "${hex}". Expected 6-digit hex (e.g., #635BFF).`);
+    }
+    const cleanHex = trimmed.replace('#', '');
+    // Parse RGB values
+    const r = Number.parseInt(cleanHex.slice(0, 2), 16) / 255;
+    const g = Number.parseInt(cleanHex.slice(2, 4), 16) / 255;
+    const b = Number.parseInt(cleanHex.slice(4, 6), 16) / 255;
+    // Convert to linear RGB
+    const [rs, gs, bs] = [r, g, b].map((c) => {
+        return c <= LINEAR_RGB_THRESHOLD
+            ? c / LINEAR_RGB_DIVISOR
+            : ((c + GAMMA_CORRECTION_OFFSET) / GAMMA_CORRECTION_DIVISOR) ** GAMMA_EXPONENT;
+    });
+    // Calculate relative luminance
+    return LUMINANCE_RED_WEIGHT * rs + LUMINANCE_GREEN_WEIGHT * gs + LUMINANCE_BLUE_WEIGHT * bs;
+}
+/**
+ * Calculates the contrast ratio between two colors according to WCAG 2.1
+ * @param color1 - First hex color string
+ * @param color2 - Second hex color string
+ * @returns Contrast ratio (1:1 to 21:1)
+ */
+export function getContrastRatio(color1, color2) {
+    const l1 = getLuminance(color1);
+    const l2 = getLuminance(color2);
+    const lighter = Math.max(l1, l2);
+    const darker = Math.min(l1, l2);
+    return (lighter + WCAG_CONTRAST_OFFSET) / (darker + WCAG_CONTRAST_OFFSET);
+}
+/**
+ * WCAG compliance levels
+ */
+export var WCAGLevel;
+(function (WCAGLevel) {
+    WCAGLevel["AA"] = "AA";
+    WCAGLevel["AA_LARGE"] = "AA_LARGE";
+    WCAGLevel["AAA"] = "AAA";
+    WCAGLevel["AAA_LARGE"] = "AAA_LARGE";
+    WCAGLevel["FAIL"] = "FAIL";
+})(WCAGLevel || (WCAGLevel = {}));
+/**
+ * Determines WCAG compliance level for a contrast ratio
+ * @param ratio - Contrast ratio
+ * @param isLargeText - Whether this is for large text (18pt+ or 14pt+ bold)
+ * @returns WCAG compliance level
+ */
+export function getWCAGLevel(ratio, isLargeText = false) {
+    if (isLargeText) {
+        if (ratio >= 4.5) {
+            return WCAGLevel.AAA_LARGE;
+        }
+        if (ratio >= 3) {
+            return WCAGLevel.AA_LARGE;
+        }
+        return WCAGLevel.FAIL;
+    }
+    if (ratio >= 7) {
+        return WCAGLevel.AAA;
+    }
+    if (ratio >= 4.5) {
+        return WCAGLevel.AA;
+    }
+    return WCAGLevel.FAIL;
+}
+/**
+ * Validates contrast between two colors
+ * @param color1 - First hex color string
+ * @param color2 - Second hex color string
+ * @param isLargeText - Whether this is for large text
+ * @returns Validation result with contrast ratio and compliance info
+ */
+export function validateContrast(color1, color2, isLargeText = false) {
+    const ratio = getContrastRatio(color1, color2);
+    const wcagLevel = getWCAGLevel(ratio, isLargeText);
+    const passesAA = ratio >= (isLargeText ? 3 : 4.5);
+    const passesAAA = ratio >= (isLargeText ? 4.5 : 7);
+    // Visual assessment based on ratio
+    let visualAssessment;
+    let recommendation;
+    if (ratio >= 7) {
+        visualAssessment = 'excellent';
+    }
+    else if (ratio >= 5) {
+        visualAssessment = 'good';
+    }
+    else if (ratio >= 4.5) {
+        visualAssessment = 'acceptable';
+        recommendation =
+            'Meets minimum WCAG AA but may be difficult to read, especially for body text. Consider using a darker/lighter color for better readability.';
+    }
+    else {
+        visualAssessment = 'poor';
+        recommendation =
+            'Does not meet WCAG AA standards. Text will be difficult to read. Strongly recommend using a color with better contrast.';
+    }
+    return {
+        color1,
+        color2,
+        ratio,
+        wcagLevel,
+        passesAA,
+        passesAAA,
+        isLargeText,
+        visualAssessment,
+        recommendation,
+    };
+}
+/**
+ * Validates multiple color combinations for WCAG compliance.
+ *
+ * @param combinations - Array of foreground/background pairs with optional label and large-text flag
+ * @returns Array of validation results, each including the input label if provided
+ */
+export function validateColorCombinations(combinations) {
+    return combinations.map((combo) => ({
+        ...validateContrast(combo.foreground, combo.background, combo.isLargeText ?? false),
+        label: combo.label,
+    }));
+}
+/**
+ * Formats a validation result as a human-readable string for display to users.
+ *
+ * @param result - Validation result, optionally with a label for the color combination
+ * @returns Multi-line string with contrast ratio, WCAG status, and recommendation (if any)
+ */
+export function formatValidationResult(result) {
+    const label = result.label ? `${result.label}: ` : '';
+    const textType = result.isLargeText ? 'large text' : 'normal text';
+    const wcagStatus = result.passesAAA ? '✅ AAA' : result.passesAA ? '✅ AA' : '❌ FAIL';
+    let output = `${label}${result.color1} on ${result.color2}\n`;
+    output += `  Contrast Ratio: ${result.ratio.toFixed(2)}:1\n`;
+    output += `  WCAG ${textType}: ${wcagStatus}\n`;
+    output += `  Visual Assessment: ${result.visualAssessment.toUpperCase()}\n`;
+    if (result.recommendation) {
+        output += `  ⚠️  ${result.recommendation}\n`;
+    }
+    return output;
+}
+//# sourceMappingURL=color-contrast.js.map

package/dist/tools/storefrontnext/site-theming/color-mapping.d.ts

@@ -0,0 +1,16 @@
+/** A foreground/background color pair for contrast validation */
+export type ColorCombination = {
+    foreground: string;
+    background: string;
+    label: string;
+    isLargeText?: boolean;
+};
+/**
+ * Builds foreground/background color combinations from a semantic color mapping.
+ * Derives pairs for text-on-background, button text, links, etc.
+ */
+export declare function buildColorCombinations(colorMapping: Record<string, string>): ColorCombination[];
+/**
+ * Appends WCAG color contrast validation results to the given instructions string.
+ */
+export declare function appendValidationSection(internalInstructions: string, combinations: ColorCombination[]): string;

package/dist/tools/storefrontnext/site-theming/color-mapping.js

@@ -0,0 +1,131 @@
+/*
+ * 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
+ */
+/**
+ * Derives foreground/background color combinations from a color mapping and
+ * appends WCAG validation results to response text.
+ *
+ * @module tools/storefrontnext/site-theming/color-mapping
+ */
+import { validateColorCombinations, formatValidationResult, isValidHex } from './color-contrast.js';
+function tryTextCombo(key, color, keyLower, ctx) {
+    if (keyLower.includes('text') && keyLower.includes('light') && isValidHex(ctx.lightBg)) {
+        return { foreground: color, background: ctx.lightBg, label: `${key}: ${color} on light background (${ctx.lightBg})` };
+    }
+    if (keyLower.includes('text') && keyLower.includes('dark') && isValidHex(ctx.darkBg)) {
+        return { foreground: color, background: ctx.darkBg, label: `${key}: ${color} on dark background (${ctx.darkBg})` };
+    }
+    const isButtonText = keyLower === 'buttontext' || (keyLower.includes('button') && keyLower.includes('text'));
+    if (isButtonText && isValidHex(ctx.buttonBg)) {
+        return {
+            foreground: color,
+            background: ctx.buttonBg,
+            label: `${key}: ${color} on button background (${ctx.buttonBg})`,
+        };
+    }
+    if (keyLower.includes('link') && isValidHex(ctx.lightBg)) {
+        return { foreground: color, background: ctx.lightBg, label: `${key}: ${color} on light background (${ctx.lightBg})` };
+    }
+    return null;
+}
+function tryBackgroundCombo(key, color, ctx) {
+    const foregroundKey = key.replace(/Background|Bg/i, 'Text') || key.replace(/Background|Bg/i, 'Foreground');
+    const foreground = ctx.colorMapping[foregroundKey] || ctx.colorMapping[`${key.replace(/Background|Bg/i, '')}Text`];
+    if (foreground?.startsWith('#') && isValidHex(foreground)) {
+        return { foreground, background: color, label: `${foregroundKey || 'text'} (${foreground}) on ${key} (${color})` };
+    }
+    return null;
+}
+function tryTextForegroundCombo(key, color, keyLower, ctx) {
+    const backgroundKey = key.replace(/Text|Foreground/i, 'Background') || key.replace(/Text|Foreground/i, 'Bg');
+    let background = ctx.colorMapping[backgroundKey];
+    let backgroundLabel = backgroundKey;
+    if (!background) {
+        background = keyLower.includes('button') ? ctx.buttonBg : keyLower.includes('dark') ? ctx.darkBg : ctx.lightBg;
+        backgroundLabel = keyLower.includes('button')
+            ? 'button background'
+            : keyLower.includes('dark')
+                ? 'dark background'
+                : 'light background';
+    }
+    if (background?.startsWith('#') && isValidHex(background)) {
+        return { foreground: color, background, label: `${key} (${color}) on ${backgroundLabel} (${background})` };
+    }
+    return null;
+}
+function tryComboForEntry(key, color, ctx) {
+    const keyLower = key.toLowerCase();
+    const textCombo = tryTextCombo(key, color, keyLower, ctx);
+    if (textCombo)
+        return textCombo;
+    if (keyLower.includes('background') || keyLower.includes('bg'))
+        return tryBackgroundCombo(key, color, ctx);
+    if (keyLower.includes('text') || keyLower.includes('foreground'))
+        return tryTextForegroundCombo(key, color, keyLower, ctx);
+    return null;
+}
+/**
+ * Builds foreground/background color combinations from a semantic color mapping.
+ * Derives pairs for text-on-background, button text, links, etc.
+ */
+export function buildColorCombinations(colorMapping) {
+    const ctx = {
+        colorMapping,
+        lightBg: colorMapping.lightBackground || colorMapping.background || '#FFFFFF',
+        darkBg: colorMapping.darkBackground || '#18181B',
+        buttonBg: colorMapping.buttonBackground || colorMapping.primary || '#0A2540',
+    };
+    const combinations = [];
+    for (const [key, color] of Object.entries(colorMapping)) {
+        if (!color || !color.startsWith('#') || !isValidHex(color))
+            continue;
+        const combo = tryComboForEntry(key, color, ctx);
+        if (combo)
+            combinations.push(combo);
+    }
+    if (combinations.length === 0) {
+        const whiteBg = '#FFFFFF';
+        const darkBgFallback = '#18181B';
+        for (const [key, color] of Object.entries(colorMapping)) {
+            if (!color || !color.startsWith('#') || !isValidHex(color))
+                continue;
+            if (key.toLowerCase().includes('background') || key.toLowerCase().includes('bg'))
+                continue;
+            combinations.push({ foreground: color, background: whiteBg, label: `${key} (${color}) on white background` }, { foreground: color, background: darkBgFallback, label: `${key} (${color}) on dark background` });
+        }
+    }
+    return combinations;
+}
+/**
+ * Appends WCAG color contrast validation results to the given instructions string.
+ */
+export function appendValidationSection(internalInstructions, combinations) {
+    if (combinations.length === 0) {
+        return internalInstructions;
+    }
+    const results = validateColorCombinations(combinations);
+    let output = internalInstructions;
+    for (const result of results) {
+        output += formatValidationResult(result);
+        output += '\n';
+    }
+    const hasIssues = results.some((r) => !r.passesAA || r.visualAssessment === 'poor' || r.visualAssessment === 'acceptable');
+    if (hasIssues) {
+        output += '### ⚠️ VALIDATION SUMMARY\n\n';
+        output += '**Issues found that should be addressed:**\n\n';
+        for (const result of results.filter((r) => !r.passesAA || r.visualAssessment === 'poor' || r.visualAssessment === 'acceptable')) {
+            output += `- ${result.label || 'Color combination'}: ${result.recommendation || 'Needs improvement'}\n`;
+        }
+        output += '\n';
+        output +=
+            '**You MUST present these findings to the user BEFORE implementing and wait for their confirmation.**\n\n';
+    }
+    else {
+        output += '### ✅ VALIDATION SUMMARY\n\n';
+        output += 'All color combinations meet WCAG AA standards and have good visual assessment.\n\n';
+    }
+    return output;
+}
+//# sourceMappingURL=color-mapping.js.map

package/dist/tools/storefrontnext/site-theming/guidance-merger.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Merges multiple ThemingGuidance objects from different theming files.
+ *
+ * @module tools/storefrontnext/site-theming/guidance-merger
+ */
+import type { ThemingGuidance } from './theming-store.js';
+/**
+ * Merges multiple ThemingGuidance objects into one.
+ * Questions are deduplicated by ID; guidelines, rules, workflows, and validations are combined.
+ */
+export declare function mergeGuidance(guidanceArray: ThemingGuidance[]): ThemingGuidance;

package/dist/tools/storefrontnext/site-theming/guidance-merger.js

@@ -0,0 +1,78 @@
+/*
+ * 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
+ */
+function mergeWorkflows(guidanceArray) {
+    const workflows = guidanceArray.filter((g) => g.workflow);
+    if (workflows.length === 0)
+        return undefined;
+    const merged = {
+        steps: [],
+        extractionInstructions: workflows[0].workflow?.extractionInstructions,
+        preImplementationChecklist: workflows[0].workflow?.preImplementationChecklist,
+    };
+    for (const g of workflows) {
+        if (g.workflow?.steps)
+            merged.steps.push(...g.workflow.steps);
+        if (!merged.extractionInstructions && g.workflow?.extractionInstructions) {
+            merged.extractionInstructions = g.workflow.extractionInstructions;
+        }
+        if (!merged.preImplementationChecklist && g.workflow?.preImplementationChecklist) {
+            merged.preImplementationChecklist = g.workflow.preImplementationChecklist;
+        }
+    }
+    return merged;
+}
+function mergeValidations(guidanceArray) {
+    const validations = guidanceArray.filter((g) => g.validation);
+    if (validations.length === 0)
+        return undefined;
+    const joinField = (field) => validations
+        .map((g) => g.validation?.[field])
+        .filter((x) => typeof x === 'string')
+        .join('\n\n');
+    return {
+        colorValidation: joinField('colorValidation'),
+        fontValidation: joinField('fontValidation'),
+        generalValidation: joinField('generalValidation'),
+        requirements: joinField('requirements'),
+    };
+}
+function buildQuestionMap(guidanceArray) {
+    const questionMap = new Map();
+    for (const guidance of guidanceArray) {
+        for (const q of guidance.questions) {
+            if (!questionMap.has(q.id))
+                questionMap.set(q.id, q);
+        }
+    }
+    return questionMap;
+}
+function buildMergedMetadata(guidanceArray) {
+    return {
+        filePath: guidanceArray.map((g) => g.metadata.filePath).join(', '),
+        fileName: guidanceArray.map((g) => g.metadata.fileName).join(', '),
+        loadedAt: new Date(),
+    };
+}
+/**
+ * Merges multiple ThemingGuidance objects into one.
+ * Questions are deduplicated by ID; guidelines, rules, workflows, and validations are combined.
+ */
+export function mergeGuidance(guidanceArray) {
+    if (guidanceArray.length === 0)
+        throw new Error('Cannot merge empty guidance array');
+    if (guidanceArray.length === 1)
+        return guidanceArray[0];
+    const questionMap = buildQuestionMap(guidanceArray);
+    return {
+        questions: [...questionMap.values()],
+        guidelines: guidanceArray.flatMap((g) => g.guidelines),
+        rules: guidanceArray.flatMap((g) => g.rules),
+        metadata: buildMergedMetadata(guidanceArray),
+        workflow: mergeWorkflows(guidanceArray),
+        validation: mergeValidations(guidanceArray),
+    };
+}
+//# sourceMappingURL=guidance-merger.js.map

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

@@ -0,0 +1,14 @@
+import type { McpTool } from '../../../utils/index.js';
+import type { Services } from '../../../services.js';
+export type { ColorEntry, ColorMapping, CollectedAnswers, ConversationContext, FontEntry, SiteThemingInput, } from './types.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 declare function createSiteThemingTool(loadServices: () => Services): McpTool;

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

@@ -0,0 +1,122 @@
+/*
+ * 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 { 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: 'storefront_next_site_theming',
+        description: '⚠️ 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'],
+        isGA: false,
+        requiresInstance: false,
+        inputSchema: {
+            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());
+            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

@@ -0,0 +1,16 @@
+/**
+ * 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;