@salesforce/b2c-tooling-sdk 0.3.0 → 0.4.1

package/dist/esm/scaffold/merge.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Options for JSON merge operations
+ */
+export interface JsonMergeOptions {
+    /** JSON path to the target location (e.g., "scripts", "hooks.dw.ocapi") */
+    jsonPath?: string;
+    /** Whether to create the path if it doesn't exist */
+    createPath?: boolean;
+}
+/**
+ * Merge JSON content into an existing JSON string
+ * @param existingJson - The existing JSON string
+ * @param newContent - JSON content to merge (string or object)
+ * @param options - Merge options
+ * @returns Updated JSON string
+ */
+export declare function mergeJson(existingJson: string, newContent: string | Record<string, unknown>, options?: JsonMergeOptions): string;
+/**
+ * Options for text insertion operations
+ */
+export interface TextInsertOptions {
+    /** Marker string to find for insert-after/insert-before */
+    marker?: string;
+    /** Whether to add a newline after the inserted content */
+    addNewline?: boolean;
+}
+/**
+ * Insert text after a marker in existing content
+ * @param existingContent - The existing text content
+ * @param newContent - Content to insert
+ * @param marker - Marker string to find
+ * @returns Updated content
+ */
+export declare function insertAfter(existingContent: string, newContent: string, marker: string): string;
+/**
+ * Insert text before a marker in existing content
+ * @param existingContent - The existing text content
+ * @param newContent - Content to insert
+ * @param marker - Marker string to find
+ * @returns Updated content
+ */
+export declare function insertBefore(existingContent: string, newContent: string, marker: string): string;
+/**
+ * Append content to the end of existing content
+ * @param existingContent - The existing text content
+ * @param newContent - Content to append
+ * @returns Updated content
+ */
+export declare function appendContent(existingContent: string, newContent: string): string;
+/**
+ * Prepend content to the beginning of existing content
+ * @param existingContent - The existing text content
+ * @param newContent - Content to prepend
+ * @returns Updated content
+ */
+export declare function prependContent(existingContent: string, newContent: string): string;

package/dist/esm/scaffold/merge.js

@@ -0,0 +1,183 @@
+/*
+ * 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
+ */
+/**
+ * Navigate to a nested JSON path and return parent + key
+ * @param obj - The object to navigate
+ * @param path - Dot-separated path (e.g., "hooks.dw.ocapi")
+ * @returns Tuple of [parent object, final key, success]
+ */
+function navigateToPath(obj, path) {
+    if (!path) {
+        return [null, '', false];
+    }
+    const parts = path.split('.');
+    const finalKey = parts.pop();
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || typeof current !== 'object') {
+            return [null, finalKey, false];
+        }
+        if (!(part in current)) {
+            return [null, finalKey, false];
+        }
+        current = current[part];
+    }
+    if (current === null || typeof current !== 'object') {
+        return [null, finalKey, false];
+    }
+    return [current, finalKey, true];
+}
+/**
+ * Create a nested path in an object
+ * @param obj - The object to modify
+ * @param path - Dot-separated path to create
+ * @returns The parent object of the final key
+ */
+function createPath(obj, path) {
+    const parts = path.split('.');
+    const finalKey = parts.pop();
+    let current = obj;
+    for (const part of parts) {
+        if (!(part in current) || typeof current[part] !== 'object' || current[part] === null) {
+            current[part] = {};
+        }
+        current = current[part];
+    }
+    return [current, finalKey];
+}
+/**
+ * Deep merge two objects, with source overriding target for conflicts
+ */
+function deepMerge(target, source) {
+    if (Array.isArray(source)) {
+        if (Array.isArray(target)) {
+            // Merge arrays by appending source items not already in target
+            const result = [...target];
+            for (const item of source) {
+                const itemStr = JSON.stringify(item);
+                const exists = result.some((existing) => JSON.stringify(existing) === itemStr);
+                if (!exists) {
+                    result.push(item);
+                }
+            }
+            return result;
+        }
+        return source;
+    }
+    if (source !== null && typeof source === 'object') {
+        if (target !== null && typeof target === 'object' && !Array.isArray(target)) {
+            const result = { ...target };
+            for (const key of Object.keys(source)) {
+                result[key] = deepMerge(result[key], source[key]);
+            }
+            return result;
+        }
+        return source;
+    }
+    return source;
+}
+/**
+ * Merge JSON content into an existing JSON string
+ * @param existingJson - The existing JSON string
+ * @param newContent - JSON content to merge (string or object)
+ * @param options - Merge options
+ * @returns Updated JSON string
+ */
+export function mergeJson(existingJson, newContent, options = {}) {
+    const existing = JSON.parse(existingJson);
+    const content = typeof newContent === 'string' ? JSON.parse(newContent) : newContent;
+    if (options.jsonPath) {
+        const [parent, key, found] = navigateToPath(existing, options.jsonPath);
+        if (!found) {
+            if (options.createPath !== false) {
+                const [newParent, newKey] = createPath(existing, options.jsonPath);
+                newParent[newKey] = content;
+            }
+            else {
+                throw new Error(`JSON path not found: ${options.jsonPath}`);
+            }
+        }
+        else if (parent) {
+            parent[key] = deepMerge(parent[key], content);
+        }
+    }
+    else {
+        // Merge at root level
+        const merged = deepMerge(existing, content);
+        return JSON.stringify(merged, null, 2);
+    }
+    return JSON.stringify(existing, null, 2);
+}
+/**
+ * Insert text after a marker in existing content
+ * @param existingContent - The existing text content
+ * @param newContent - Content to insert
+ * @param marker - Marker string to find
+ * @returns Updated content
+ */
+export function insertAfter(existingContent, newContent, marker) {
+    const index = existingContent.indexOf(marker);
+    if (index === -1) {
+        throw new Error(`Marker not found: ${marker}`);
+    }
+    let insertPoint = index + marker.length;
+    // If there's a newline right after the marker, insert after it
+    if (existingContent[insertPoint] === '\n') {
+        insertPoint++;
+    }
+    // Check if we need to add a newline before the new content
+    const needsNewlineBefore = insertPoint > 0 && existingContent[insertPoint - 1] !== '\n' && !newContent.startsWith('\n');
+    // Check if we need to add a newline after the new content
+    const needsNewlineAfter = !newContent.endsWith('\n') && insertPoint < existingContent.length && existingContent[insertPoint] !== '\n';
+    return (existingContent.slice(0, insertPoint) +
+        (needsNewlineBefore ? '\n' : '') +
+        newContent +
+        (needsNewlineAfter ? '\n' : '') +
+        existingContent.slice(insertPoint));
+}
+/**
+ * Insert text before a marker in existing content
+ * @param existingContent - The existing text content
+ * @param newContent - Content to insert
+ * @param marker - Marker string to find
+ * @returns Updated content
+ */
+export function insertBefore(existingContent, newContent, marker) {
+    const index = existingContent.indexOf(marker);
+    if (index === -1) {
+        throw new Error(`Marker not found: ${marker}`);
+    }
+    // Check if we need to add a newline before the new content
+    const needsNewlineBefore = index > 0 && existingContent[index - 1] !== '\n' && !newContent.startsWith('\n');
+    // Check if we need to add a newline after the new content (before marker)
+    const needsNewlineAfter = !newContent.endsWith('\n');
+    return (existingContent.slice(0, index) +
+        (needsNewlineBefore ? '\n' : '') +
+        newContent +
+        (needsNewlineAfter ? '\n' : '') +
+        existingContent.slice(index));
+}
+/**
+ * Append content to the end of existing content
+ * @param existingContent - The existing text content
+ * @param newContent - Content to append
+ * @returns Updated content
+ */
+export function appendContent(existingContent, newContent) {
+    const needsNewline = existingContent.length > 0 && !existingContent.endsWith('\n');
+    return existingContent + (needsNewline ? '\n' : '') + newContent;
+}
+/**
+ * Prepend content to the beginning of existing content
+ * @param existingContent - The existing text content
+ * @param newContent - Content to prepend
+ * @returns Updated content
+ */
+export function prependContent(existingContent, newContent) {
+    const needsNewline = !newContent.endsWith('\n') && existingContent.length > 0;
+    return newContent + (needsNewline ? '\n' : '') + existingContent;
+}
+//# sourceMappingURL=merge.js.map

package/dist/esm/scaffold/merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.js","sourceRoot":"","sources":["../../../src/scaffold/merge.ts"],"names":[],"mappings":"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"}

package/dist/esm/scaffold/parameter-resolver.d.ts

@@ -0,0 +1,86 @@
+import type { B2CInstance } from '../instance/index.js';
+import type { Scaffold, ScaffoldParameter, ScaffoldChoice } from './types.js';
+/**
+ * Options for resolving scaffold parameters.
+ */
+export interface ResolveParametersOptions {
+    /** Pre-provided variables (from flags, env, etc.) */
+    providedVariables?: Record<string, string | boolean | string[]>;
+    /** Project root for resolving local sources */
+    projectRoot?: string;
+    /** B2C instance for resolving remote sources (sites) */
+    b2cInstance?: B2CInstance;
+    /** Use defaults for missing values instead of erroring */
+    useDefaults?: boolean;
+}
+/**
+ * Error encountered during parameter validation.
+ */
+export interface ParameterResolutionError {
+    /** Parameter name */
+    parameter: string;
+    /** Error message */
+    message: string;
+    /** The invalid value, if applicable */
+    value?: unknown;
+    /** Available choices, if applicable */
+    availableChoices?: string[];
+}
+/**
+ * Result of resolving scaffold parameters.
+ */
+export interface ResolvedParameters {
+    /** All resolved variable values */
+    variables: Record<string, string | boolean | string[]>;
+    /** Parameters still missing values (need prompting) */
+    missingParameters: ScaffoldParameter[];
+    /** Validation errors encountered */
+    errors: ParameterResolutionError[];
+}
+/**
+ * Schema for a resolved parameter with source choices populated.
+ */
+export interface ResolvedParameterSchema {
+    /** Parameter definition */
+    parameter: ScaffoldParameter;
+    /** Resolved choices from dynamic source */
+    resolvedChoices?: ScaffoldChoice[];
+    /** Path map for cartridges (name -> absolute path) */
+    pathMap?: Map<string, string>;
+    /** Warning message if source resolution failed */
+    warning?: string;
+}
+/**
+ * Resolve scaffold parameters by:
+ * 1. Validating provided variables against sources
+ * 2. Setting companion path variables for cartridges
+ * 3. Applying defaults where appropriate
+ * 4. Filtering by condition (`when` field)
+ * 5. Collecting missing required parameters
+ *
+ * @param scaffold - The scaffold to resolve parameters for
+ * @param options - Resolution options
+ * @returns Resolved parameters, missing parameters, and any errors
+ */
+export declare function resolveScaffoldParameters(scaffold: Scaffold, options?: ResolveParametersOptions): Promise<ResolvedParameters>;
+/**
+ * Parse key=value option strings into variables object.
+ * Handles boolean values and array values for multi-choice params.
+ *
+ * @param options - Array of "key=value" strings
+ * @param scaffold - Optional scaffold for multi-choice detection
+ * @returns Variables object
+ */
+export declare function parseParameterOptions(options: string[], scaffold?: Scaffold): Record<string, boolean | string | string[]>;
+/**
+ * Get parameter metadata with resolved source choices.
+ * Useful for MCP/other consumers to build input schemas.
+ *
+ * @param scaffold - The scaffold to get parameter schemas for
+ * @param options - Options for resolving sources
+ * @returns Array of resolved parameter schemas
+ */
+export declare function getParameterSchemas(scaffold: Scaffold, options?: {
+    projectRoot?: string;
+    b2cInstance?: B2CInstance;
+}): Promise<ResolvedParameterSchema[]>;

package/dist/esm/scaffold/parameter-resolver.js

@@ -0,0 +1,179 @@
+/*
+ * 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 { evaluateCondition } from './validators.js';
+import { resolveLocalSource, resolveRemoteSource, isRemoteSource, validateAgainstSource } from './sources.js';
+/**
+ * Resolve scaffold parameters by:
+ * 1. Validating provided variables against sources
+ * 2. Setting companion path variables for cartridges
+ * 3. Applying defaults where appropriate
+ * 4. Filtering by condition (`when` field)
+ * 5. Collecting missing required parameters
+ *
+ * @param scaffold - The scaffold to resolve parameters for
+ * @param options - Resolution options
+ * @returns Resolved parameters, missing parameters, and any errors
+ */
+export async function resolveScaffoldParameters(scaffold, options = {}) {
+    const { providedVariables = {}, projectRoot = process.cwd(), useDefaults = false } = options;
+    const variables = { ...providedVariables };
+    const missingParameters = [];
+    const errors = [];
+    // Cache for cartridge paths (only resolved once if needed)
+    let cartridgePathMap;
+    for (const param of scaffold.manifest.parameters) {
+        // Check if conditional parameter should be evaluated
+        if (param.when && !evaluateCondition(param.when, variables)) {
+            continue;
+        }
+        // If value was already provided, validate it against source
+        if (variables[param.name] !== undefined && param.source) {
+            const providedValue = String(variables[param.name]);
+            const validation = validateAgainstSource(param.source, providedValue, projectRoot);
+            if (!validation.valid) {
+                errors.push({
+                    parameter: param.name,
+                    message: `Invalid value "${providedValue}" for ${param.name}. Available ${param.source}: ${validation.availableChoices?.join(', ') || 'none'}`,
+                    value: providedValue,
+                    availableChoices: validation.availableChoices,
+                });
+                continue;
+            }
+            // Set companion path variable for cartridges source
+            if (param.source === 'cartridges') {
+                if (!cartridgePathMap) {
+                    const result = resolveLocalSource('cartridges', projectRoot);
+                    cartridgePathMap = result.pathMap;
+                }
+                const cartridgePath = cartridgePathMap?.get(providedValue);
+                if (cartridgePath) {
+                    variables[`${param.name}Path`] = cartridgePath;
+                }
+            }
+            continue;
+        }
+        // Skip if already provided (no source validation needed)
+        if (variables[param.name] !== undefined) {
+            continue;
+        }
+        // Use default if available and useDefaults is enabled
+        if (useDefaults && param.default !== undefined) {
+            variables[param.name] = param.default;
+            // Set companion path variable for cartridges source with default value
+            if (param.source === 'cartridges' && typeof param.default === 'string') {
+                if (!cartridgePathMap) {
+                    const result = resolveLocalSource('cartridges', projectRoot);
+                    cartridgePathMap = result.pathMap;
+                }
+                const cartridgePath = cartridgePathMap?.get(param.default);
+                if (cartridgePath) {
+                    variables[`${param.name}Path`] = cartridgePath;
+                }
+            }
+            continue;
+        }
+        // Parameter is missing - track it
+        if (param.required || param.default === undefined) {
+            missingParameters.push(param);
+        }
+        else if (param.default !== undefined) {
+            // Optional parameter with default - apply it
+            variables[param.name] = param.default;
+        }
+    }
+    return { variables, missingParameters, errors };
+}
+/**
+ * Parse key=value option strings into variables object.
+ * Handles boolean values and array values for multi-choice params.
+ *
+ * @param options - Array of "key=value" strings
+ * @param scaffold - Optional scaffold for multi-choice detection
+ * @returns Variables object
+ */
+export function parseParameterOptions(options, scaffold) {
+    const variables = {};
+    // Build set of multi-choice parameter names
+    const multiChoiceParams = new Set();
+    if (scaffold) {
+        for (const param of scaffold.manifest.parameters) {
+            if (param.type === 'multi-choice') {
+                multiChoiceParams.add(param.name);
+            }
+        }
+    }
+    for (const opt of options) {
+        const eqIndex = opt.indexOf('=');
+        if (eqIndex === -1) {
+            // No equals sign - treat as boolean flag
+            variables[opt] = true;
+        }
+        else {
+            const key = opt.slice(0, Math.max(0, eqIndex));
+            const value = opt.slice(Math.max(0, eqIndex + 1));
+            if (value === 'true') {
+                variables[key] = true;
+            }
+            else if (value === 'false') {
+                variables[key] = false;
+            }
+            else if (multiChoiceParams.has(key)) {
+                // Split comma-separated values for multi-choice parameters
+                variables[key] = value.split(',').map((v) => v.trim());
+            }
+            else {
+                variables[key] = value;
+            }
+        }
+    }
+    return variables;
+}
+/**
+ * Get parameter metadata with resolved source choices.
+ * Useful for MCP/other consumers to build input schemas.
+ *
+ * @param scaffold - The scaffold to get parameter schemas for
+ * @param options - Options for resolving sources
+ * @returns Array of resolved parameter schemas
+ */
+export async function getParameterSchemas(scaffold, options = {}) {
+    const { projectRoot = process.cwd(), b2cInstance } = options;
+    const schemas = [];
+    for (const param of scaffold.manifest.parameters) {
+        const schema = { parameter: param };
+        if (param.source) {
+            if (isRemoteSource(param.source)) {
+                // Remote source - needs B2C instance
+                if (b2cInstance) {
+                    try {
+                        schema.resolvedChoices = await resolveRemoteSource(param.source, b2cInstance);
+                    }
+                    catch (error) {
+                        schema.warning = `Could not fetch ${param.source}: ${error.message}`;
+                        schema.resolvedChoices = [];
+                    }
+                }
+                else {
+                    schema.warning = `Remote source '${param.source}' requires B2C instance`;
+                    schema.resolvedChoices = [];
+                }
+            }
+            else {
+                // Local source
+                const result = resolveLocalSource(param.source, projectRoot);
+                schema.resolvedChoices = result.choices;
+                schema.pathMap = result.pathMap;
+            }
+        }
+        else if (param.choices) {
+            // Static choices
+            schema.resolvedChoices = param.choices;
+        }
+        schemas.push(schema);
+    }
+    return schemas;
+}
+//# sourceMappingURL=parameter-resolver.js.map

package/dist/esm/scaffold/parameter-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parameter-resolver.js","sourceRoot":"","sources":["../../../src/scaffold/parameter-resolver.ts"],"names":[],"mappings":"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"}

package/dist/esm/scaffold/registry.d.ts

@@ -0,0 +1,45 @@
+import type { Scaffold, ScaffoldDiscoveryOptions, ScaffoldProvider, ScaffoldTransformer } from './types.js';
+/**
+ * Scaffold registry for discovering and managing scaffolds
+ */
+export declare class ScaffoldRegistry {
+    private providers;
+    private transformers;
+    private scaffoldCache;
+    /**
+     * Add scaffold providers
+     */
+    addProviders(providers: ScaffoldProvider[]): void;
+    /**
+     * Add scaffold transformers
+     */
+    addTransformers(transformers: ScaffoldTransformer[]): void;
+    /**
+     * Clear the scaffold cache
+     */
+    clearCache(): void;
+    /**
+     * Get all scaffolds from all sources
+     * @param options - Discovery options
+     * @returns Array of scaffolds (deduplicated by name, later sources override earlier)
+     */
+    getScaffolds(options?: ScaffoldDiscoveryOptions): Promise<Scaffold[]>;
+    /**
+     * Get a specific scaffold by ID
+     * @param id - Scaffold ID
+     * @param options - Discovery options
+     * @returns Scaffold or null if not found
+     */
+    getScaffold(id: string, options?: ScaffoldDiscoveryOptions): Promise<Scaffold | null>;
+    /**
+     * Search scaffolds by query
+     * @param query - Search query
+     * @param options - Additional discovery options
+     * @returns Matching scaffolds
+     */
+    searchScaffolds(query: string, options?: ScaffoldDiscoveryOptions): Promise<Scaffold[]>;
+}
+/**
+ * Create a new scaffold registry instance
+ */
+export declare function createScaffoldRegistry(): ScaffoldRegistry;