@salesforce/b2c-dx-mcp 0.4.4 → 0.4.6

package/dist/tools/scapi/scapi-custom-api-scaffold.d.ts

@@ -0,0 +1,60 @@
+import type { Services } from '../../services.js';
+import type { McpTool } from '../../utils/index.js';
+import type { Scaffold, ResolvedParameters, ResolveParametersOptions } from '@salesforce/b2c-tooling-sdk/scaffold';
+/** Optional overrides for testing (scaffold not found, missing required). */
+export interface ScaffoldCustomApiExecuteOverrides {
+    getScaffold?: (id: string, opts: {
+        projectRoot: string;
+    }) => Promise<null | Scaffold>;
+    resolveScaffoldParameters?: (scaffold: Scaffold, opts: ResolveParametersOptions) => Promise<ResolvedParameters>;
+}
+/**
+ * Input schema for scapi_custom_api_scaffold tool.
+ * Parameters match the custom-api scaffold: apiName, apiType, cartridgeName, etc.
+ */
+interface ScaffoldCustomApiInput {
+    /** API name (kebab-case, e.g. my-products). Required. */
+    apiName: string;
+    /** Cartridge name that will contain the API. Optional; defaults to first cartridge found in project. */
+    cartridgeName?: string;
+    /** API type: admin (no siteId) or shopper (siteId, customer-facing). Default: shopper */
+    apiType?: 'admin' | 'shopper';
+    /** Short description of the API. Default: "A custom B2C Commerce API" */
+    apiDescription?: string;
+    /** Project root for cartridge discovery and output. Default: MCP project directory */
+    projectRoot?: string;
+    /** Output directory override. Default: scaffold default or project root */
+    outputDir?: string;
+}
+/**
+ * Output schema for scapi_custom_api_scaffold tool.
+ */
+interface ScaffoldCustomApiOutput {
+    scaffold: string;
+    outputDir: string;
+    dryRun: boolean;
+    files: Array<{
+        path: string;
+        action: string;
+        skipReason?: string;
+    }>;
+    postInstructions?: string;
+    error?: string;
+}
+/**
+ * Core execute logic for the custom API scaffold tool.
+ * Exported for tests so we can inject getScaffold / resolveScaffoldParameters and cover error branches.
+ */
+export declare function executeScaffoldCustomApi(args: ScaffoldCustomApiInput, services: Services, overrides?: ScaffoldCustomApiExecuteOverrides): Promise<ScaffoldCustomApiOutput>;
+/**
+ * Creates the scapi_custom_api_scaffold tool.
+ *
+ * Uses @salesforce/b2c-tooling-sdk scaffold: registry, resolveScaffoldParameters,
+ * resolveOutputDirectory, generateFromScaffold. cartridgeName must be a cartridge
+ * discovered under projectRoot (e.g. from .project or cartridges/).
+ *
+ * @param loadServices - Function that returns Services (used by adapter on each call).
+ * @param executeOverrides - Optional overrides for testing (getScaffold, resolveScaffoldParameters).
+ */
+export declare function createScaffoldCustomApiTool(loadServices: () => Services, executeOverrides?: ScaffoldCustomApiExecuteOverrides): McpTool;
+export {};

package/dist/tools/scapi/scapi-custom-api-scaffold.js

@@ -0,0 +1,175 @@
+/*
+ * 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
+ */
+/**
+ * SCAPI Custom API Scaffold tool.
+ *
+ * Generates a new custom SCAPI endpoint using the SDK's custom-api scaffold
+ * (schema.yaml, api.json, script.js).
+ *
+ * @module tools/scapi/scapi-custom-api-scaffold
+ */
+import { z } from 'zod';
+import { createToolAdapter, jsonResult, errorResult } from '../adapter.js';
+import { createScaffoldRegistry, generateFromScaffold, resolveScaffoldParameters, resolveOutputDirectory, } from '@salesforce/b2c-tooling-sdk/scaffold';
+import { findCartridges } from '@salesforce/b2c-tooling-sdk/operations/code';
+const CUSTOM_API_SCAFFOLD_ID = 'custom-api';
+/**
+ * Core execute logic for the custom API scaffold tool.
+ * Exported for tests so we can inject getScaffold / resolveScaffoldParameters and cover error branches.
+ */
+export async function executeScaffoldCustomApi(args, services, overrides) {
+    const projectRoot = services.resolveWithProjectDirectory(args.projectRoot);
+    const getScaffold = overrides?.getScaffold ??
+        (async (id, opts) => {
+            const registry = createScaffoldRegistry();
+            return registry.getScaffold(id, opts);
+        });
+    const scaffold = await getScaffold(CUSTOM_API_SCAFFOLD_ID, { projectRoot });
+    if (!scaffold) {
+        return {
+            scaffold: CUSTOM_API_SCAFFOLD_ID,
+            outputDir: projectRoot,
+            dryRun: false,
+            files: [],
+            error: `Scaffold not found: ${CUSTOM_API_SCAFFOLD_ID}. Ensure @salesforce/b2c-tooling-sdk is installed.`,
+        };
+    }
+    const cartridges = findCartridges(projectRoot);
+    if (cartridges.length === 0) {
+        return {
+            scaffold: CUSTOM_API_SCAFFOLD_ID,
+            outputDir: projectRoot,
+            dryRun: false,
+            files: [],
+            error: 'No cartridges found in project. Custom API scaffold requires an existing cartridge. Create a cartridge first: use `b2c scaffold cartridge --name app_custom`, or manually create a directory with a `.project` file (e.g., cartridges/app_custom/.project).',
+        };
+    }
+    let cartridgeName = args.cartridgeName;
+    if (!cartridgeName) {
+        cartridgeName = cartridges[0].name;
+    }
+    const providedVariables = {
+        apiName: args.apiName,
+        cartridgeName,
+        includeExampleEndpoints: true,
+    };
+    if (args.apiType !== undefined)
+        providedVariables.apiType = args.apiType;
+    if (args.apiDescription !== undefined)
+        providedVariables.apiDescription = args.apiDescription;
+    const resolveParams = overrides?.resolveScaffoldParameters ?? resolveScaffoldParameters;
+    const resolved = await resolveParams(scaffold, {
+        providedVariables,
+        projectRoot,
+        useDefaults: true,
+    });
+    if (resolved.errors.length > 0) {
+        const message = resolved.errors.map((e) => `${e.parameter}: ${e.message}`).join('; ');
+        return {
+            scaffold: CUSTOM_API_SCAFFOLD_ID,
+            outputDir: projectRoot,
+            dryRun: false,
+            files: [],
+            error: `Parameter validation failed: ${message}`,
+        };
+    }
+    const missingRequired = resolved.missingParameters.filter((p) => p.required);
+    if (missingRequired.length > 0) {
+        return {
+            scaffold: CUSTOM_API_SCAFFOLD_ID,
+            outputDir: projectRoot,
+            dryRun: false,
+            files: [],
+            error: `Missing required parameter: ${missingRequired[0].name}. For cartridgeName, ensure the cartridge exists in the project (under projectRoot).`,
+        };
+    }
+    const outputDir = resolveOutputDirectory({
+        outputDir: args.outputDir,
+        scaffold,
+        projectRoot,
+    });
+    try {
+        const result = await generateFromScaffold(scaffold, {
+            outputDir,
+            variables: resolved.variables,
+            dryRun: false,
+            force: false,
+        });
+        return {
+            scaffold: CUSTOM_API_SCAFFOLD_ID,
+            outputDir,
+            dryRun: result.dryRun,
+            files: result.files.map((f) => ({
+                path: f.path,
+                action: f.action,
+                skipReason: f.skipReason,
+            })),
+            postInstructions: result.postInstructions,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            scaffold: CUSTOM_API_SCAFFOLD_ID,
+            outputDir,
+            dryRun: false,
+            files: [],
+            error: `Scaffold generation failed: ${message}`,
+        };
+    }
+}
+/**
+ * Creates the scapi_custom_api_scaffold tool.
+ *
+ * Uses @salesforce/b2c-tooling-sdk scaffold: registry, resolveScaffoldParameters,
+ * resolveOutputDirectory, generateFromScaffold. cartridgeName must be a cartridge
+ * discovered under projectRoot (e.g. from .project or cartridges/).
+ *
+ * @param loadServices - Function that returns Services (used by adapter on each call).
+ * @param executeOverrides - Optional overrides for testing (getScaffold, resolveScaffoldParameters).
+ */
+export function createScaffoldCustomApiTool(loadServices, executeOverrides) {
+    return createToolAdapter({
+        name: 'scapi_custom_api_scaffold',
+        description: `Generate a new custom SCAPI endpoint (OAS 3.0 schema, api.json, script.js) in an existing cartridge. \
+Required: apiName (kebab-case). Optional: cartridgeName (defaults to first cartridge found in project), apiType (shopper|admin) default to shopper, \
+apiDescription, projectRoot, outputDir.`,
+        toolsets: ['PWAV3', 'SCAPI', 'STOREFRONTNEXT'],
+        isGA: false,
+        requiresInstance: false,
+        inputSchema: {
+            apiName: z
+                .string()
+                .min(1)
+                .describe('API name in kebab-case (e.g. my-products). Must start with lowercase letter, only letters, numbers, hyphens.'),
+            cartridgeName: z
+                .string()
+                .min(1)
+                .nullish()
+                .describe('Cartridge name that will contain the API. Optional; omit to use the first cartridge found under project root).'),
+            apiType: z
+                .enum(['admin', 'shopper'])
+                .optional()
+                .describe('Admin (no siteId) or shopper (siteId, customer-facing). Default: shopper'),
+            apiDescription: z.string().optional().describe('Short description of the API.'),
+            projectRoot: z
+                .string()
+                .nullish()
+                .describe('Project root for cartridge discovery. Default: project directory. Set to override the project directory.'),
+            outputDir: z.string().optional().describe('Output directory override. Default: project root'),
+        },
+        async execute(args, { services }) {
+            return executeScaffoldCustomApi(args, services, executeOverrides);
+        },
+        formatOutput(output) {
+            if (output.error) {
+                return errorResult(output.error);
+            }
+            return jsonResult(output);
+        },
+    }, loadServices);
+}
+//# sourceMappingURL=scapi-custom-api-scaffold.js.map

package/dist/tools/storefrontnext/figma/figma-to-component/figma-url-parser.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Extracted parameters from a Figma design URL.
+ *
+ * @property {string} fileKey - Figma file identifier from URL path
+ * @property {string} nodeId - Node identifier (colon format for Figma MCP)
+ */
+export interface FigmaParams {
+    fileKey: string;
+    nodeId: string;
+}
+/**
+ * Parses a Figma URL to extract fileKey and nodeId.
+ *
+ * Supported URL formats:
+ * - https://figma.com/design/:fileKey/:fileName?node-id=1-2
+ * - https://www.figma.com/design/:fileKey/:fileName?node-id=1-2
+ * - https://figma.com/file/:fileKey/:fileName?node-id=1-2
+ *
+ * @param figmaUrl - The Figma URL to parse
+ * @returns Object with fileKey and nodeId
+ * @throws {Error} When URL is not from figma.com, fileKey cannot be extracted, or node-id is missing
+ * @throws {TypeError} When URL format is invalid
+ */
+export declare function parseFigmaUrl(figmaUrl: string): FigmaParams;

package/dist/tools/storefrontnext/figma/figma-to-component/figma-url-parser.js

@@ -0,0 +1,53 @@
+/*
+ * 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
+ */
+/**
+ * Parses a Figma URL to extract fileKey and nodeId.
+ *
+ * Supported URL formats:
+ * - https://figma.com/design/:fileKey/:fileName?node-id=1-2
+ * - https://www.figma.com/design/:fileKey/:fileName?node-id=1-2
+ * - https://figma.com/file/:fileKey/:fileName?node-id=1-2
+ *
+ * @param figmaUrl - The Figma URL to parse
+ * @returns Object with fileKey and nodeId
+ * @throws {Error} When URL is not from figma.com, fileKey cannot be extracted, or node-id is missing
+ * @throws {TypeError} When URL format is invalid
+ */
+export function parseFigmaUrl(figmaUrl) {
+    try {
+        const url = new URL(figmaUrl);
+        // Validate it's a Figma URL
+        if (!url.hostname.includes('figma.com')) {
+            throw new Error('URL must be from figma.com');
+        }
+        // Extract fileKey from pathname
+        // Pattern: /design/:fileKey/:fileName or /file/:fileKey/:fileName
+        const pathMatch = url.pathname.match(/\/(design|file)\/([^/]+)/);
+        if (!pathMatch || !pathMatch[2]) {
+            throw new Error('Could not extract fileKey from URL. Expected format: https://figma.com/design/:fileKey/:fileName');
+        }
+        const fileKey = pathMatch[2];
+        // Extract nodeId from query params
+        // Pattern: ?node-id=1-2 or ?node-id=1:2
+        const nodeIdParam = url.searchParams.get('node-id');
+        if (!nodeIdParam) {
+            throw new Error('Could not extract node-id from URL. Expected query parameter: ?node-id=1-2');
+        }
+        // Convert node-id format from "1-2" to "1:2" (Figma MCP expects colon format)
+        const nodeId = nodeIdParam.replaceAll('-', ':');
+        return {
+            fileKey,
+            nodeId,
+        };
+    }
+    catch (error) {
+        if (error instanceof TypeError) {
+            throw new TypeError(`Invalid URL format: ${figmaUrl}`);
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=figma-url-parser.js.map

package/dist/tools/storefrontnext/figma/figma-to-component/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Figma-to-component workflow orchestrator tool.
+ *
+ * Parses Figma URLs, loads workflow instructions, and returns step-by-step guidance
+ * for converting Figma designs to Storefront Next components.
+ *
+ * @module tools/storefrontnext/figma/figma-to-component
+ */
+import { z } from 'zod';
+import type { McpTool } from '../../../../utils/index.js';
+import type { Services } from '../../../../services.js';
+export declare const figmaToComponentSchema: z.ZodObject<{
+    figmaUrl: z.ZodString;
+    workflowFilePath: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    figmaUrl: string;
+    workflowFilePath?: string | undefined;
+}, {
+    figmaUrl: string;
+    workflowFilePath?: string | undefined;
+}>;
+export type FigmaToComponentInput = z.infer<typeof figmaToComponentSchema>;
+export interface WorkflowConfig {
+    /** YAML frontmatter key-value pairs. Parsed for future use (e.g., taskType-specific behavior). */
+    metadata: Record<string, string>;
+    content: string;
+}
+/**
+ * Generates the workflow guide for Figma-to-component conversion.
+ *
+ * @param figmaUrl - Figma design URL with node-id query parameter
+ * @param workflowFilePath - Optional absolute path to custom workflow .md file; uses built-in default if omitted
+ * @returns Formatted workflow guide string with Figma parameters and step-by-step instructions, or error message if URL or workflow file is invalid
+ */
+export declare function generateWorkflowResponse(figmaUrl: string, workflowFilePath?: string): string;
+/**
+ * Creates the storefront_next_figma_to_component_workflow MCP tool.
+ *
+ * @param loadServices - Function that loads configuration and returns Services instance
+ * @returns MCP tool for workflow orchestration
+ */
+export declare function createFigmaToComponentTool(loadServices: () => Services): McpTool;