@salesforce/b2c-dx-mcp 2.0.0 → 2.1.0

package/dist/tools/storefrontnext/figma/map-tokens/token-matcher.d.ts

@@ -1,65 +0,0 @@
-import type { ThemeToken, ParsedTheme } from './css-parser.js';
-/**
- * Design token extracted from Figma.
- *
- * @property {string} name - Token name from Figma (e.g., "Primary/Blue", "Spacing/Large")
- * @property {string} value - Token value (e.g., "#2563eb", "16px", "0.5rem")
- * @property {'color'|'fontFamily'|'fontSize'|'opacity'|'other'|'radius'|'spacing'} type - Token type for matching logic
- * @property {string} [description] - Optional description from Figma
- */
-export interface FigmaToken {
-    name: string;
-    value: string;
-    type: 'color' | 'fontFamily' | 'fontSize' | 'opacity' | 'other' | 'radius' | 'spacing';
-    description?: string;
-}
-/**
- * Result of matching a Figma token to theme tokens.
- *
- * @property {FigmaToken} figmaToken - The Figma token that was matched
- * @property {ThemeToken} [matchedToken] - Best-matching theme token (if found)
- * @property {number} confidence - Match confidence (0-100)
- * @property {'exact'|'fuzzy'|'none'} matchType - 'exact', 'fuzzy', or 'none'
- * @property {string} reason - Human-readable explanation of the match
- * @property {TokenSuggestion[]} [suggestions] - Suggested new tokens or alternatives (when no match or fuzzy match)
- */
-export interface TokenMatch {
-    figmaToken: FigmaToken;
-    matchedToken?: ThemeToken;
-    confidence: number;
-    matchType: 'exact' | 'fuzzy' | 'none';
-    reason: string;
-    suggestions?: TokenSuggestion[];
-}
-/**
- * Suggestion for a new or alternative theme token.
- *
- * @property {string} tokenName - Suggested CSS custom property name
- * @property {string} value - Token value
- * @property {'both'|'dark'|'light'} theme - Which theme(s) to add to: 'both', 'dark', or 'light'
- * @property {string} reason - Explanation for the suggestion
- * @property {string} [insertAfter] - Optional token name to insert after in the theme file
- */
-export interface TokenSuggestion {
-    tokenName: string;
-    value: string;
-    theme: 'both' | 'dark' | 'light';
-    reason: string;
-    insertAfter?: string;
-}
-/**
- * Matches a single Figma token to existing theme tokens.
- *
- * @param figmaToken - Figma design token to match
- * @param parsedTheme - Parsed theme from app.css
- * @returns TokenMatch with exact, fuzzy, or no match and optional suggestions
- */
-export declare function matchToken(figmaToken: FigmaToken, parsedTheme: ParsedTheme): TokenMatch;
-/**
- * Matches multiple Figma tokens to existing theme tokens.
- *
- * @param figmaTokens - Array of Figma design tokens to match
- * @param parsedTheme - Parsed theme from app.css
- * @returns Array of TokenMatch results, one per input token
- */
-export declare function matchTokens(figmaTokens: FigmaToken[], parsedTheme: ParsedTheme): TokenMatch[];

package/dist/tools/storefrontnext/figma/map-tokens/token-matcher.js

@@ -1,268 +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
- */
-/**
- * Normalizes hex colors to lowercase 6-digit format
- */
-function normalizeHexColor(hex) {
-    let normalized = hex.toLowerCase().trim();
-    // Remove # if present
-    if (normalized.startsWith('#')) {
-        normalized = normalized.slice(1);
-    }
-    // Expand 3-digit hex to 6-digit
-    if (normalized.length === 3) {
-        normalized = [...normalized].map((c) => c + c).join('');
-    }
-    return normalized;
-}
-/**
- * Calculates color distance between two hex colors (0-100, lower is closer)
- */
-function calculateColorDistance(hex1, hex2) {
-    const r1 = Number.parseInt(hex1.slice(0, 2), 16);
-    const g1 = Number.parseInt(hex1.slice(2, 4), 16);
-    const b1 = Number.parseInt(hex1.slice(4, 6), 16);
-    const r2 = Number.parseInt(hex2.slice(0, 2), 16);
-    const g2 = Number.parseInt(hex2.slice(2, 4), 16);
-    const b2 = Number.parseInt(hex2.slice(4, 6), 16);
-    // Euclidean distance normalized to 0-100 scale
-    const distance = Math.hypot(r1 - r2, g1 - g2, b1 - b2);
-    // Max distance is sqrt(255^2 * 3) ≈ 441
-    return (distance / 441) * 100;
-}
-/**
- * Calculates string similarity between two strings (0-100, higher is more similar)
- * Uses Levenshtein distance algorithm
- */
-function calculateStringSimilarity(str1, str2) {
-    const s1 = str1.toLowerCase();
-    const s2 = str2.toLowerCase();
-    // Exact match
-    if (s1 === s2)
-        return 100;
-    // Contains match bonus
-    if (s1.includes(s2) || s2.includes(s1)) {
-        return 80 + (Math.min(s1.length, s2.length) / Math.max(s1.length, s2.length)) * 20;
-    }
-    // Levenshtein distance
-    const matrix = [];
-    const len1 = s1.length;
-    const len2 = s2.length;
-    for (let i = 0; i <= len1; i++) {
-        matrix[i] = [i];
-    }
-    for (let j = 0; j <= len2; j++) {
-        matrix[0][j] = j;
-    }
-    for (let i = 1; i <= len1; i++) {
-        for (let j = 1; j <= len2; j++) {
-            const cost = s1[i - 1] === s2[j - 1] ? 0 : 1;
-            matrix[i][j] = Math.min(matrix[i - 1][j] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j - 1] + cost);
-        }
-    }
-    const distance = matrix[len1][len2];
-    const maxLen = Math.max(len1, len2);
-    return ((maxLen - distance) / maxLen) * 100;
-}
-/**
- * Extracts semantic meaning from token name
- */
-function extractSemantics(name) {
-    const parts = name.toLowerCase().replace(/^--/, '').split(/[-_]/);
-    const semantics = [];
-    // Color semantics
-    const colorKeywords = new Set([
-        'accent',
-        'background',
-        'border',
-        'destructive',
-        'error',
-        'foreground',
-        'info',
-        'muted',
-        'primary',
-        'secondary',
-        'success',
-        'text',
-        'warning',
-    ]);
-    const lightDark = new Set(['dark', 'light']);
-    const colorNames = new Set(['black', 'blue', 'gray', 'green', 'orange', 'purple', 'red', 'white', 'yellow']);
-    for (const part of parts) {
-        if (colorKeywords.has(part)) {
-            semantics.push(`semantic:${part}`);
-        }
-        if (lightDark.has(part)) {
-            semantics.push(`theme:${part}`);
-        }
-        if (colorNames.has(part)) {
-            semantics.push(`color:${part}`);
-        }
-    }
-    return semantics;
-}
-/**
- * Finds exact color match
- */
-function findExactColorMatch(figmaValue, parsedTheme) {
-    const normalizedFigma = normalizeHexColor(figmaValue);
-    for (const token of parsedTheme.tokens) {
-        if (token.type === 'color' && token.resolvedValue) {
-            const normalizedToken = normalizeHexColor(token.resolvedValue);
-            if (normalizedFigma === normalizedToken) {
-                return token;
-            }
-        }
-    }
-    return null;
-}
-/**
- * Finds fuzzy matches based on color similarity and name similarity
- */
-function findFuzzyMatches(figmaToken, parsedTheme) {
-    const matches = [];
-    // Filter tokens by type
-    const relevantTokens = parsedTheme.tokens.filter((token) => token.type === figmaToken.type);
-    const figmaSemantics = extractSemantics(figmaToken.name);
-    const normalizedFigmaValue = figmaToken.type === 'color' && figmaToken.value.startsWith('#')
-        ? normalizeHexColor(figmaToken.value)
-        : figmaToken.value;
-    for (const token of relevantTokens) {
-        let score = 0;
-        // Name similarity (40% weight)
-        const nameSimilarity = calculateStringSimilarity(figmaToken.name, token.name);
-        score += nameSimilarity * 0.4;
-        // Semantic similarity (30% weight)
-        const tokenSemantics = extractSemantics(token.name);
-        const semanticMatches = figmaSemantics.filter((s) => tokenSemantics.includes(s)).length;
-        const semanticScore = figmaSemantics.length > 0 ? (semanticMatches / figmaSemantics.length) * 100 : 0;
-        score += semanticScore * 0.3;
-        // Value similarity (30% weight)
-        if (figmaToken.type === 'color' && token.resolvedValue) {
-            const normalizedTokenValue = normalizeHexColor(token.resolvedValue);
-            const colorDistance = calculateColorDistance(normalizedFigmaValue, normalizedTokenValue);
-            const colorSimilarity = Math.max(0, 100 - colorDistance);
-            score += colorSimilarity * 0.3;
-        }
-        if (score > 20) {
-            // Only include matches with score > 20
-            matches.push({ token, score });
-        }
-    }
-    // Sort by score descending
-    return matches.sort((a, b) => b.score - a.score);
-}
-/**
- * Generates suggestions for new tokens if no good match found
- */
-function generateTokenSuggestions(figmaToken, parsedTheme) {
-    const suggestions = [];
-    // Analyze existing token naming patterns
-    const existingNames = parsedTheme.tokens.filter((t) => t.type === figmaToken.type).map((t) => t.name);
-    // Extract common prefixes
-    const hasColorPrefix = existingNames.some((n) => n.startsWith('--color-'));
-    const hasRadiusPrefix = existingNames.some((n) => n.startsWith('--radius-'));
-    // Generate token name based on Figma token name
-    let suggestedName = figmaToken.name.toLowerCase().replaceAll(/[^a-z0-9-]/g, '-');
-    // Add appropriate prefix if not present
-    if (figmaToken.type === 'color' && !suggestedName.startsWith('--color-') && hasColorPrefix) {
-        suggestedName = `--color-${suggestedName.replace(/^--/, '')}`;
-    }
-    else if (figmaToken.type === 'radius' && !suggestedName.startsWith('--radius-') && hasRadiusPrefix) {
-        suggestedName = `--radius-${suggestedName.replace(/^--/, '')}`;
-    }
-    else if (!suggestedName.startsWith('--')) {
-        suggestedName = `--${suggestedName}`;
-    }
-    // Find a good place to insert
-    const similarTokens = existingNames.filter((name) => {
-        const similarity = calculateStringSimilarity(name, suggestedName);
-        return similarity > 30;
-    });
-    const insertAfter = similarTokens.length > 0 ? similarTokens[0] : undefined;
-    // For colors, suggest both light and dark values
-    if (figmaToken.type === 'color') {
-        suggestions.push({
-            tokenName: suggestedName,
-            value: figmaToken.value,
-            theme: 'both',
-            reason: `New token suggestion based on Figma token "${figmaToken.name}"`,
-            insertAfter,
-        });
-    }
-    else {
-        suggestions.push({
-            tokenName: suggestedName,
-            value: figmaToken.value,
-            theme: 'light',
-            reason: `New token suggestion based on Figma token "${figmaToken.name}"`,
-            insertAfter,
-        });
-    }
-    return suggestions;
-}
-/**
- * Matches a single Figma token to existing theme tokens.
- *
- * @param figmaToken - Figma design token to match
- * @param parsedTheme - Parsed theme from app.css
- * @returns TokenMatch with exact, fuzzy, or no match and optional suggestions
- */
-export function matchToken(figmaToken, parsedTheme) {
-    // Try exact match first (only for colors with hex values)
-    if (figmaToken.type === 'color' && figmaToken.value.startsWith('#')) {
-        const exactMatch = findExactColorMatch(figmaToken.value, parsedTheme);
-        if (exactMatch) {
-            return {
-                figmaToken,
-                matchedToken: exactMatch,
-                confidence: 100,
-                matchType: 'exact',
-                reason: `Exact color match: ${figmaToken.value} matches ${exactMatch.name}`,
-            };
-        }
-    }
-    // Try fuzzy matching
-    const fuzzyMatches = findFuzzyMatches(figmaToken, parsedTheme);
-    if (fuzzyMatches.length > 0 && fuzzyMatches[0].score >= 50) {
-        const bestMatch = fuzzyMatches[0];
-        return {
-            figmaToken,
-            matchedToken: bestMatch.token,
-            confidence: Math.round(bestMatch.score),
-            matchType: 'fuzzy',
-            reason: `Fuzzy match based on name similarity and semantic meaning`,
-            suggestions: fuzzyMatches.length > 1
-                ? fuzzyMatches.slice(1, 4).map((m) => ({
-                    tokenName: m.token.name,
-                    value: m.token.value,
-                    theme: m.token.theme === 'shared' ? 'both' : m.token.theme,
-                    reason: `Alternative match (confidence: ${Math.round(m.score)}%)`,
-                }))
-                : undefined,
-        };
-    }
-    // No good match found, generate suggestions
-    const suggestions = generateTokenSuggestions(figmaToken, parsedTheme);
-    return {
-        figmaToken,
-        confidence: 0,
-        matchType: 'none',
-        reason: 'No matching token found. Consider creating a new token.',
-        suggestions,
-    };
-}
-/**
- * Matches multiple Figma tokens to existing theme tokens.
- *
- * @param figmaTokens - Array of Figma design tokens to match
- * @param parsedTheme - Parsed theme from app.css
- * @returns Array of TokenMatch results, one per input token
- */
-export function matchTokens(figmaTokens, parsedTheme) {
-    return figmaTokens.map((token) => matchToken(token, parsedTheme));
-}
-//# sourceMappingURL=token-matcher.js.map

package/dist/tools/storefrontnext/index.d.ts

@@ -1,30 +0,0 @@
-/**
- * Storefront Next (deprecated) toolset for B2C Commerce.
- *
- * **DEPRECATED:** These `sfnext_*` tools are superseded by the `storefront-next`
- * and `storefront-next-figma` agent-skills plugins and are NOT compatible with
- * the Storefront Next 1.0 GA release. They now live in the
- * `STOREFRONTNEXT_DEPRECATED` toolset, which is never auto-activated by project
- * detection and is excluded from `--toolsets ALL`. To use them you must request
- * the toolset explicitly (`--toolsets STOREFRONTNEXT_DEPRECATED`). They will be
- * removed in a future release.
- *
- * **Implemented Tools:**
- * - `sfnext_get_guidelines` - Get development guidelines and best practices
- * - `sfnext_add_page_designer_decorator` - Add Page Designer decorators to React components
- * - `sfnext_configure_theme` - Get theming guidelines, questions, and validation
- * - `sfnext_start_figma_workflow` - Convert Figma to components
- * - `sfnext_analyze_component` - Analyze design and recommend REUSE/EXTEND/CREATE
- * - `sfnext_match_tokens_to_theme` - Match design tokens to theme
- *
- * @module tools/storefrontnext
- */
-import type { McpTool } from '../../utils/index.js';
-import type { Services } from '../../services.js';
-/**
- * Creates all tools for the deprecated STOREFRONTNEXT_DEPRECATED toolset.
- *
- * @param loadServices - Function that loads configuration and returns Services instance
- * @returns Array of MCP tools
- */
-export declare function createStorefrontNextTools(loadServices: () => Promise<Services> | Services): McpTool[];

package/dist/tools/storefrontnext/index.js

@@ -1,28 +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 { createDeveloperGuidelinesTool } from './sfnext-development-guidelines.js';
-import { createPageDesignerDecoratorTool } from './page-designer-decorator/index.js';
-import { createSiteThemingTool } from './site-theming/index.js';
-import { createFigmaToComponentTool } from './figma/figma-to-component/index.js';
-import { createGenerateComponentTool } from './figma/generate-component/index.js';
-import { createMapTokensToThemeTool } from './figma/map-tokens/index.js';
-/**
- * Creates all tools for the deprecated STOREFRONTNEXT_DEPRECATED toolset.
- *
- * @param loadServices - Function that loads configuration and returns Services instance
- * @returns Array of MCP tools
- */
-export function createStorefrontNextTools(loadServices) {
-    return [
-        createDeveloperGuidelinesTool(loadServices),
-        createPageDesignerDecoratorTool(loadServices),
-        createSiteThemingTool(loadServices),
-        createFigmaToComponentTool(loadServices),
-        createGenerateComponentTool(loadServices),
-        createMapTokensToThemeTool(loadServices),
-    ];
-}
-//# sourceMappingURL=index.js.map

package/dist/tools/storefrontnext/page-designer-decorator/analyzer.d.ts

@@ -1,169 +0,0 @@
-/**
- * Component analysis result
- */
-export interface ComponentInfo {
-    componentName: string;
-    interfaceName: null | string;
-    hasDecorators: boolean;
-    props: PropInfo[];
-    exportType: 'default' | 'named';
-    filePath: string;
-}
-/**
- * Property information extracted from component interface
- */
-export interface PropInfo {
-    name: string;
-    type: string;
-    optional: boolean;
-    isComplex: boolean;
-    isUIOnly: boolean;
-}
-/**
- * Type suggestion for attribute configuration
- */
-export interface TypeSuggestion {
-    type: string;
-    reason: string;
-    priority: 'high' | 'low' | 'medium';
-}
-/**
- * Valid SFCC Page Designer attribute types
- */
-export declare const VALID_ATTRIBUTE_TYPES: readonly ["string", "text", "markup", "integer", "boolean", "product", "category", "file", "page", "image", "url", "enum", "custom", "cms_record"];
-/**
- * Infer Page Designer attribute type from TypeScript type
- */
-export declare function inferPageDesignerType(tsType: string): string;
-/**
- * Check if TypeScript type can be auto-inferred
- */
-export declare function isAutoInferredType(tsType: string): boolean;
-/**
- * Check if type is too complex for Page Designer
- */
-export declare function isComplexType(tsType: string): boolean;
-/**
- * Check if property is UI-only
- */
-export declare function isUIOnlyProp(propName: string): boolean;
-/**
- * Generate Page Designer attribute type suggestions for a component prop
- *
- * **Inference Strategy:**
- * Uses naming patterns and TypeScript types to suggest appropriate Page Designer types.
- * This reduces manual configuration by auto-detecting common patterns.
- *
- * **Page Designer Types:**
- * - `string`: Default text input
- * - `url`: URL/link inputs (validates URL format)
- * - `image`: Image asset picker
- * - `html`: Rich text editor
- * - `markup`: HTML/markdown editor
- * - `enum`: Dropdown with predefined values
- * - `boolean`: Checkbox
- * - `number`: Numeric input
- * - `product`: Product picker (SFCC-specific)
- * - `category`: Category picker (SFCC-specific)
- *
- * **Heuristics (by priority):**
- * 1. **High Priority**: Strong patterns (url, image, product)
- * 2. **Medium Priority**: Contextual patterns (html, markup)
- * 3. **Low Priority**: Weak signals (description → markup)
- *
- * Multiple suggestions allow developers to choose the best fit.
- *
- * @param propName - Property name from component interface
- * @param tsType - TypeScript type string
- * @returns Array of type suggestions with reasoning and priority
- *
- * @example
- * // URL detection:
- * generateTypeSuggestions('imageUrl', 'string')
- * // => [{ type: 'url', reason: '...', priority: 'high' }]
- *
- * @example
- * // Image detection:
- * generateTypeSuggestions('heroImage', 'string')
- * // => [{ type: 'image', reason: '...', priority: 'high' }]
- *
- * @example
- * // Multiple suggestions:
- * generateTypeSuggestions('description', 'string')
- * // => [
- * //   { type: 'markup', reason: '...', priority: 'low' },
- * //   { type: 'html', reason: '...', priority: 'medium' }
- * // ]
- *
- * @example
- * // Product reference:
- * generateTypeSuggestions('product', 'string')
- * // => [{ type: 'product', reason: '...', priority: 'high' }]
- *
- * @public
- */
-export declare function generateTypeSuggestions(propName: string, tsType: string): TypeSuggestion[];
-/**
- * Component analyzer for Page Designer decorator generation
- */
-declare class ComponentAnalyzer {
-    private cache;
-    analyzeComponent(filePath: string): ComponentInfo;
-    clearCache(): void;
-}
-export declare const componentAnalyzer: ComponentAnalyzer;
-/**
- * Resolve component input (name or path) to absolute file path
- *
- * **This is the main entry point for component discovery.**
- *
- * Supports two input modes:
- * 1. **Name-based** (recommended): Just provide the component name
- * 2. **Path-based** (backward compatible): Provide relative path from workspace
- *
- * **Name-based detection:**
- * Input is treated as a name if it:
- * - Does NOT contain path separators (/ or \)
- * - Does NOT have a file extension (.tsx, .ts, etc.)
- *
- * **Path-based detection:**
- * Input is treated as a path if it:
- * - Contains / or \
- * - Has a file extension
- *
- * @param input - Component name or relative path
- * @param workspaceRoot - Absolute path to workspace root
- * @param searchPaths - Additional directories to search (only used for name-based)
- * @returns Absolute file path to component
- * @throws {Error} If component cannot be found, with detailed search information
- *
- * @example
- * // Name-based (finds automatically):
- * resolveComponent('ProductCard', '/workspace')
- * // => '/workspace/src/components/product-tile/ProductCard.tsx'
- *
- * @example
- * // Path-based (backward compatible):
- * resolveComponent('src/components/ProductCard.tsx', '/workspace')
- * // => '/workspace/src/components/ProductCard.tsx'
- *
- * @example
- * // With custom search paths (for monorepos):
- * resolveComponent('Hero', '/workspace', ['packages/retail/src', 'packages/shared'])
- * // => '/workspace/packages/retail/src/components/Hero.tsx'
- *
- * @example
- * // Error handling:
- * try {
- *   resolveComponent('NonExistent', '/workspace')
- * } catch (err) {
- *   // Error includes:
- *   // - List of searched locations
- *   // - Tried name variations
- *   // - Helpful tips for resolution
- * }
- *
- * @public
- */
-export declare function resolveComponent(input: string, workspaceRoot: string, searchPaths?: string[]): string;
-export {};