@salesforce/b2c-dx-mcp 0.4.3 → 0.4.5

package/dist/services.js

@@ -233,18 +233,6 @@ export class Services {
         }
         return this.b2cInstance.webdav;
     }
-    /**
-     * Get the project project directory.
-     * Falls back to process.cwd() if not explicitly set.
-     *
-     * This is the directory where the project is located, which may differ from process.cwd()
-     * when MCP clients spawn servers from a different location (e.g., home directory).
-     *
-     * @returns Project project directory path
-     */
-    getWorkingDirectory() {
-        return this.resolvedConfig.values.projectDirectory ?? process.cwd();
-    }
     /**
      * Join path segments.
      *
@@ -285,6 +273,25 @@ export class Services {
     resolvePath(...segments) {
         return path.resolve(...segments);
     }
+    /**
+     * Resolve a path relative to the project directory.
+     * If path is not supplied, returns the project directory.
+     * If path is absolute, returns it as-is.
+     * If path is relative, resolves it relative to the project directory.
+     *
+     * @param pathArg - Optional path to resolve
+     * @returns Resolved absolute path
+     */
+    resolveWithProjectDirectory(pathArg) {
+        const projectDir = this.resolvedConfig.values.projectDirectory ?? process.cwd();
+        if (!pathArg) {
+            return projectDir;
+        }
+        if (path.isAbsolute(pathArg)) {
+            return pathArg;
+        }
+        return path.resolve(projectDir, pathArg);
+    }
     /**
      * Get file or directory stats.
      *

package/dist/tools/cartridges/index.js

@@ -10,7 +10,6 @@
  *
  * @module tools/cartridges
  */
-import path from 'node:path';
 import { z } from 'zod';
 import { createToolAdapter, jsonResult } from '../adapter.js';
 import { findAndDeployCartridges, getActiveCodeVersion } from '@salesforce/b2c-tooling-sdk/operations/code';
@@ -84,11 +83,7 @@ function createCartridgeDeployTool(loadServices, injections) {
                     instance.config.codeVersion = codeVersion;
                 }
                 // Resolve directory path: relative paths are resolved relative to project directory, absolute paths are used as-is
-                const directory = args.directory
-                    ? path.isAbsolute(args.directory)
-                        ? args.directory
-                        : path.resolve(context.services.getWorkingDirectory(), args.directory)
-                    : context.services.getWorkingDirectory();
+                const directory = context.services.resolveWithProjectDirectory(args.directory);
                 // Parse options
                 const options = {
                     include: args.cartridges,

package/dist/tools/index.d.ts

@@ -3,10 +3,7 @@
  *
  * This module exports all available tools and utilities.
  * Tools use the @salesforce/b2c-tooling-sdk operations layer directly.
- *
- * > ⚠️ **PLACEHOLDER - ACTIVE DEVELOPMENT**
- * > Tools are currently placeholder implementations that return mock responses.
- * > Actual implementations are coming soon. Use `--allow-non-ga-tools` flag to enable.
+ * Use `--allow-non-ga-tools` flag to enable tools (preview release).
  *
  * @module tools
  */

package/dist/tools/index.js

@@ -8,10 +8,7 @@
  *
  * This module exports all available tools and utilities.
  * Tools use the @salesforce/b2c-tooling-sdk operations layer directly.
- *
- * > ⚠️ **PLACEHOLDER - ACTIVE DEVELOPMENT**
- * > Tools are currently placeholder implementations that return mock responses.
- * > Actual implementations are coming soon. Use `--allow-non-ga-tools` flag to enable.
+ * Use `--allow-non-ga-tools` flag to enable tools (preview release).
  *
  * @module tools
  */

package/dist/tools/mrt/index.js

@@ -10,7 +10,6 @@
  *
  * @module tools/mrt
  */
-import path from 'node:path';
 import { z } from 'zod';
 import { createToolAdapter, jsonResult } from '../adapter.js';
 import { pushBundle } from '@salesforce/b2c-tooling-sdk/operations/mrt';
@@ -75,11 +74,7 @@ function createMrtBundlePushTool(loadServices, injections) {
             // Parse comma-separated glob patterns (same as CLI defaults)
             const ssrOnly = (args.ssrOnly || 'ssr.js,ssr.mjs,server/**/*').split(',').map((s) => s.trim());
             const ssrShared = (args.ssrShared || 'static/**/*,client/**/*').split(',').map((s) => s.trim());
-            const buildDirectory = args.buildDirectory
-                ? path.isAbsolute(args.buildDirectory)
-                    ? args.buildDirectory
-                    : path.resolve(context.services.getWorkingDirectory(), args.buildDirectory)
-                : path.join(context.services.getWorkingDirectory(), 'build');
+            const buildDirectory = context.services.resolveWithProjectDirectory(args.buildDirectory || 'build');
             // Log all computed variables before pushing bundle
             const logger = getLogger();
             logger.debug({

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

@@ -1,11 +1,20 @@
+/**
+ * PWA Kit v3 toolset for B2C Commerce.
+ *
+ * This toolset provides MCP tools for PWA Kit v3 development.
+ * PWA Kit-specific tools are planned for future releases.
+ * mrt_bundle_push (from MRT toolset) is available for PWAV3 projects.
+ *
+ * @module tools/pwav3
+ */
 import type { McpTool } from '../../utils/index.js';
 import type { Services } from '../../services.js';
 /**
  * Creates all tools for the PWAV3 toolset.
  *
- * Note: mrt_bundle_push is defined in the MRT toolset with
- * toolsets: ["MRT", "PWAV3", "STOREFRONTNEXT"] and will
- * automatically appear in PWAV3.
+ * PWA Kit-specific tools are not yet implemented. mrt_bundle_push is defined
+ * in the MRT toolset with toolsets: ["MRT", "PWAV3", "STOREFRONTNEXT"] and
+ * automatically appears in PWAV3 for bundle deployment.
  *
  * @param loadServices - Function that loads configuration and returns Services instance
  * @returns Array of MCP tools

package/dist/tools/pwav3/index.js

@@ -3,76 +3,18 @@
  * 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
  */
-/**
- * PWA Kit v3 toolset for B2C Commerce.
- *
- * This toolset provides MCP tools for PWA Kit v3 development.
- *
- * > ⚠️ **PLACEHOLDER - ACTIVE DEVELOPMENT**
- * > Tools in this module are placeholder implementations that return mock responses.
- * > Actual implementations are coming soon. Use `--allow-non-ga-tools` flag to enable.
- *
- * @module tools/pwav3
- */
-import { z } from 'zod';
-import { createToolAdapter, jsonResult } from '../adapter.js';
-/**
- * Creates a placeholder tool for PWA Kit development.
- *
- * Placeholder tools log invocations and return mock responses until
- * the actual implementation is available.
- *
- * @param name - Tool name
- * @param description - Tool description
- * @param toolsets - Toolsets this tool belongs to
- * @param loadServices - Function that loads configuration and returns Services instance
- * @returns The configured MCP tool
- */
-function createPlaceholderTool(name, description, toolsets, loadServices) {
-    return createToolAdapter({
-        name,
-        description: `[PLACEHOLDER] ${description}`,
-        toolsets,
-        isGA: false,
-        requiresInstance: false,
-        inputSchema: {
-            message: z.string().optional().describe('Optional message to echo'),
-        },
-        async execute(args) {
-            // Placeholder implementation
-            const timestamp = new Date().toISOString();
-            return {
-                tool: name,
-                status: 'placeholder',
-                message: `This is a placeholder implementation for '${name}'. The actual implementation is coming soon.`,
-                input: args,
-                timestamp,
-            };
-        },
-        formatOutput: (output) => jsonResult(output),
-    }, loadServices);
-}
+import { createDeveloperGuidelinesTool } from './pwa-kit-development-guidelines.js';
 /**
  * Creates all tools for the PWAV3 toolset.
  *
- * Note: mrt_bundle_push is defined in the MRT toolset with
- * toolsets: ["MRT", "PWAV3", "STOREFRONTNEXT"] and will
- * automatically appear in PWAV3.
+ * PWA Kit-specific tools are not yet implemented. mrt_bundle_push is defined
+ * in the MRT toolset with toolsets: ["MRT", "PWAV3", "STOREFRONTNEXT"] and
+ * automatically appears in PWAV3 for bundle deployment.
  *
  * @param loadServices - Function that loads configuration and returns Services instance
  * @returns Array of MCP tools
  */
 export function createPwav3Tools(loadServices) {
-    return [
-        // PWA Kit development tools
-        createPlaceholderTool('pwakit_create_storefront', 'Create a new PWA Kit storefront project', ['PWAV3'], loadServices),
-        createPlaceholderTool('pwakit_create_page', 'Create a new page component in PWA Kit project', ['PWAV3'], loadServices),
-        createPlaceholderTool('pwakit_create_component', 'Create a new React component in PWA Kit project', ['PWAV3'], loadServices),
-        createPlaceholderTool('pwakit_get_dev_guidelines', 'Get PWA Kit development guidelines and best practices', ['PWAV3'], loadServices),
-        createPlaceholderTool('pwakit_recommend_hooks', 'Recommend appropriate React hooks for PWA Kit use cases', ['PWAV3'], loadServices),
-        createPlaceholderTool('pwakit_run_site_test', 'Run site tests for PWA Kit project', ['PWAV3'], loadServices),
-        createPlaceholderTool('pwakit_install_agent_rules', 'Install AI agent rules for PWA Kit development', ['PWAV3'], loadServices),
-        createPlaceholderTool('pwakit_explore_scapi_shop_api', 'Explore SCAPI Shop API endpoints and capabilities', ['PWAV3'], loadServices),
-    ];
+    return [createDeveloperGuidelinesTool(loadServices)];
 }
 //# sourceMappingURL=index.js.map

package/dist/tools/pwav3/pwa-kit-development-guidelines.d.ts

@@ -0,0 +1,9 @@
+import type { McpTool } from '../../utils/index.js';
+import type { Services } from '../../services.js';
+/**
+ * Creates the developer guidelines tool for PWA Kit.
+ *
+ * @param loadServices - Function that loads configuration and returns Services instance
+ * @returns The configured MCP tool
+ */
+export declare function createDeveloperGuidelinesTool(loadServices: () => Services): McpTool;

package/dist/tools/pwav3/pwa-kit-development-guidelines.js

@@ -0,0 +1,151 @@
+/*
+ * 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
+ */
+/**
+ * Developer Guidelines tool for PWA Kit.
+ *
+ * Provides critical development guidelines and best practices for building
+ * PWA Kit applications with React, Chakra UI, and Commerce API.
+ *
+ * @module tools/pwav3/pwa-kit-development-guidelines
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { z } from 'zod';
+import { createToolAdapter, textResult } from '../adapter.js';
+// Resolve the content directory from the package root
+const require = createRequire(import.meta.url);
+const packageRoot = path.dirname(require.resolve('@salesforce/b2c-dx-mcp/package.json'));
+const CONTENT_DIR = path.join(packageRoot, 'content', 'pwav3');
+/**
+ * Section metadata with key and optional description.
+ * Single source of truth for all available sections.
+ */
+const SECTIONS_METADATA = [
+    { key: 'quick-reference', description: null }, // Meta-section, excluded from topics list
+    {
+        key: 'components',
+        description: 'component patterns, Chakra UI, special components (_app, _app-config, _error), React Hooks',
+    },
+    {
+        key: 'data-fetching',
+        description: 'commerce-sdk-react hooks, useCustomQuery/useCustomMutation, React Query, custom APIs, caching',
+    },
+    {
+        key: 'routing',
+        description: 'Express.js, React Router, configureRoutes, SSR/CSR navigation, withReactQuery, getProps patterns',
+    },
+    {
+        key: 'config',
+        description: 'configuration files, environment variables, file precedence, proxy setup, multi-site',
+    },
+    {
+        key: 'state-management',
+        description: 'Context API, useReducer, Redux integration, AppConfig methods',
+    },
+    {
+        key: 'extensibility',
+        description: 'template extension, ccExtensibility configuration, overrides directory',
+    },
+    { key: 'testing', description: 'Jest, React Testing Library, MSW, test organization, coverage' },
+    {
+        key: 'i18n',
+        description: 'React Intl, translation extraction/compilation, multi-locale support',
+    },
+    { key: 'styling', description: 'Chakra UI theming, Emotion CSS-in-JS, responsive design' },
+];
+/**
+ * Derived: array of section keys for validation.
+ */
+const _SECTIONS = SECTIONS_METADATA.map((s) => s.key);
+/**
+ * Generates the topics list for the tool description.
+ * Excludes meta-sections (like quick-reference) that don't have descriptions.
+ * @returns Comma-separated list of topics
+ */
+function generateTopicsList() {
+    return SECTIONS_METADATA.filter((s) => s.description !== null)
+        .map((s) => s.description)
+        .join(', ');
+}
+/**
+ * Detailed section content loaded from markdown files.
+ * Built dynamically from SECTIONS_METADATA to avoid duplication.
+ */
+const SECTION_CONTENT = Object.fromEntries(SECTIONS_METADATA.map((section) => {
+    const filename = `${section.key}.md`;
+    const filePath = path.join(CONTENT_DIR, filename);
+    const content = readFileSync(filePath, 'utf8');
+    return [section.key, content];
+}));
+/**
+ * Default sections to return when no sections are specified.
+ * Includes quick-reference plus the most critical detailed sections
+ * to provide comprehensive guidelines by default.
+ */
+const DEFAULT_SECTIONS = ['quick-reference', 'components', 'data-fetching', 'routing'];
+/**
+ * Creates the developer guidelines tool for PWA Kit.
+ *
+ * @param loadServices - Function that loads configuration and returns Services instance
+ * @returns The configured MCP tool
+ */
+export function createDeveloperGuidelinesTool(loadServices) {
+    return createToolAdapter({
+        name: 'pwakit_development_guidelines',
+        description: 'ESSENTIAL FIRST STEP for PWA Kit v3 development. Returns critical architecture rules, coding standards, and best practices. ' +
+            'Use this tool FIRST before writing any PWA Kit code to understand non-negotiable patterns for React components, ' +
+            'data fetching, routing, configuration, and framework constraints. Returns comprehensive guidelines by default (quick-reference + key sections); ' +
+            'supports retrieving specific topic sections. ' +
+            'CRITICAL INSTRUCTION: ALWAYS present ALL returned content in FULL - DO NOT SUMMARIZE, DO NOT ADD SUMMARIES, ' +
+            'DO NOT ADD OVERVIEWS. The returned content IS the complete answer - display it exactly as provided.',
+        toolsets: ['PWAV3'],
+        isGA: false,
+        requiresInstance: false,
+        inputSchema: {
+            sections: z
+                .array(z.enum([..._SECTIONS]))
+                .optional()
+                .describe('Optional array of specific sections to retrieve. If not specified, returns comprehensive guidelines ' +
+                '(quick-reference, components, data-fetching, routing). ' +
+                'CRITICAL: Present ALL returned content in FULL - DO NOT SUMMARIZE. ' +
+                'Available sections: quick-reference, components, data-fetching, routing, config, state-management, ' +
+                'extensibility, testing, i18n, styling. ' +
+                `Topics covered: ${generateTopicsList()}. ` +
+                'Content is complete - present exactly as provided, no summaries.'),
+        },
+        async execute(args) {
+            // Handle empty array case explicitly
+            if (args.sections && args.sections.length === 0) {
+                return '';
+            }
+            // Default to comprehensive set of key sections if no sections specified
+            const sections = args.sections || DEFAULT_SECTIONS;
+            // Multiple sections: combine with separators
+            const combinedContent = sections.map((section) => SECTION_CONTENT[section]).join('\n\n---\n\n');
+            // Apply instructions for all multi-section responses to ensure full content display
+            const isMultiSection = sections.length > 1;
+            // Prepend explicit instruction to present full content (not summarized)
+            const fullContentInstruction = isMultiSection
+                ? '⚠️ CRITICAL: Display the FULL content below. DO NOT summarize, condense, or add overviews.\n\n' +
+                    '📋 PWA KIT DEVELOPMENT GUIDELINES\n\n' +
+                    '---\n\n'
+                : '';
+            // Add footer instruction to reinforce the message for multi-section responses
+            const footerInstruction = isMultiSection
+                ? '\n\n---\n\n⚠️ END OF CONTENT - Full content displayed above. Do not add summaries.\n'
+                : '';
+            // For single sections, return directly (backward compatible)
+            // For multiple sections, wrap with instructions
+            if (sections.length === 1) {
+                return SECTION_CONTENT[sections[0]];
+            }
+            return fullContentInstruction + combinedContent + footerInstruction;
+        },
+        formatOutput: (output) => textResult(output),
+    }, loadServices);
+}
+//# sourceMappingURL=pwa-kit-development-guidelines.js.map

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

@@ -2,7 +2,7 @@
  * SCAPI toolset for B2C Commerce.
  *
  * This toolset provides MCP tools for Salesforce Commerce API (SCAPI) discovery and exploration.
- * Includes both standard SCAPI schemas and custom API status tools.
+ * Includes standard SCAPI schemas, custom API status, and custom API scaffold tools.
  *
  * @module tools/scapi
  */

package/dist/tools/scapi/index.js

@@ -5,6 +5,7 @@
  */
 import { createScapiSchemasListTool } from './scapi-schemas-list.js';
 import { createScapiCustomApisStatusTool } from './scapi-custom-apis-status.js';
+import { createScaffoldCustomApiTool } from './scapi-custom-api-scaffold.js';
 /**
  * Creates all tools for the SCAPI toolset.
  *
@@ -12,6 +13,10 @@ import { createScapiCustomApisStatusTool } from './scapi-custom-apis-status.js';
  * @returns Array of MCP tools
  */
 export function createScapiTools(loadServices) {
-    return [createScapiSchemasListTool(loadServices), createScapiCustomApisStatusTool(loadServices)];
+    return [
+        createScapiSchemasListTool(loadServices),
+        createScapiCustomApisStatusTool(loadServices),
+        createScaffoldCustomApiTool(loadServices),
+    ];
 }
 //# sourceMappingURL=index.js.map

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