@salesforce/b2c-tooling-sdk 0.3.0 → 0.4.0

package/dist/cjs/scaffold/registry.js

@@ -0,0 +1,219 @@
+/*
+ * 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 fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { glob } from 'glob';
+import { SCAFFOLDS_DATA_DIR } from './types.js';
+import { validateScaffoldManifest } from './validators.js';
+import { getLogger } from '../logging/logger.js';
+/**
+ * Load a scaffold manifest from a directory
+ * @param scaffoldDir - Path to the scaffold directory
+ * @param source - Source type for this scaffold
+ * @returns Scaffold object or null if invalid
+ */
+async function loadScaffold(scaffoldDir, source) {
+    const manifestPath = path.join(scaffoldDir, 'scaffold.json');
+    try {
+        const manifestContent = await fs.readFile(manifestPath, 'utf-8');
+        const manifest = JSON.parse(manifestContent);
+        // Validate manifest
+        const errors = validateScaffoldManifest(manifest);
+        if (errors.length > 0) {
+            const logger = getLogger();
+            logger.warn({ manifestPath, errors }, 'Invalid scaffold manifest');
+            return null;
+        }
+        const filesPath = path.join(scaffoldDir, 'files');
+        // Check if files directory exists
+        try {
+            await fs.access(filesPath);
+        }
+        catch {
+            const logger = getLogger();
+            logger.warn({ scaffoldDir }, 'Scaffold has no files/ directory');
+            return null;
+        }
+        return {
+            id: manifest.name,
+            manifest,
+            path: scaffoldDir,
+            filesPath,
+            source,
+        };
+    }
+    catch {
+        // Manifest doesn't exist or is invalid JSON
+        return null;
+    }
+}
+/**
+ * Discover scaffolds from a directory
+ * @param baseDir - Base directory to search
+ * @param source - Source type for scaffolds found here
+ * @returns Array of discovered scaffolds
+ */
+async function discoverScaffoldsFromDir(baseDir, source) {
+    const scaffolds = [];
+    try {
+        await fs.access(baseDir);
+    }
+    catch {
+        // Directory doesn't exist
+        return scaffolds;
+    }
+    // Find all scaffold.json files
+    const manifestPaths = await glob('*/scaffold.json', {
+        cwd: baseDir,
+        absolute: false,
+    });
+    for (const manifestPath of manifestPaths) {
+        const scaffoldDir = path.join(baseDir, path.dirname(manifestPath));
+        const scaffold = await loadScaffold(scaffoldDir, source);
+        if (scaffold) {
+            scaffolds.push(scaffold);
+        }
+    }
+    return scaffolds;
+}
+/**
+ * Filter scaffolds based on discovery options
+ */
+function filterScaffolds(scaffolds, options) {
+    let filtered = scaffolds;
+    // Filter by category
+    if (options.category) {
+        filtered = filtered.filter((s) => s.manifest.category === options.category);
+    }
+    // Filter by source
+    if (options.sources && options.sources.length > 0) {
+        filtered = filtered.filter((s) => options.sources.includes(s.source));
+    }
+    // Filter by search query
+    if (options.query) {
+        const query = options.query.toLowerCase();
+        filtered = filtered.filter((s) => {
+            const searchText = [s.manifest.name, s.manifest.displayName, s.manifest.description].join(' ').toLowerCase();
+            return searchText.includes(query);
+        });
+    }
+    return filtered;
+}
+/**
+ * Scaffold registry for discovering and managing scaffolds
+ */
+export class ScaffoldRegistry {
+    providers = [];
+    transformers = [];
+    scaffoldCache = new Map();
+    /**
+     * Add scaffold providers
+     */
+    addProviders(providers) {
+        this.providers.push(...providers);
+        this.clearCache();
+    }
+    /**
+     * Add scaffold transformers
+     */
+    addTransformers(transformers) {
+        this.transformers.push(...transformers);
+        this.clearCache();
+    }
+    /**
+     * Clear the scaffold cache
+     */
+    clearCache() {
+        this.scaffoldCache.clear();
+    }
+    /**
+     * Get all scaffolds from all sources
+     * @param options - Discovery options
+     * @returns Array of scaffolds (deduplicated by name, later sources override earlier)
+     */
+    async getScaffolds(options = {}) {
+        const cacheKey = JSON.stringify(options);
+        if (this.scaffoldCache.has(cacheKey)) {
+            return this.scaffoldCache.get(cacheKey);
+        }
+        // Collect scaffolds from all sources in priority order
+        const allScaffolds = [];
+        // 1. Run 'before' providers
+        const beforeProviders = this.providers.filter((p) => p.priority === 'before');
+        for (const provider of beforeProviders) {
+            const providerScaffolds = await provider.getScaffolds(options);
+            allScaffolds.push(...providerScaffolds);
+        }
+        // 2. Built-in scaffolds (lowest priority for built-ins)
+        const builtInScaffolds = await discoverScaffoldsFromDir(SCAFFOLDS_DATA_DIR, 'built-in');
+        allScaffolds.push(...builtInScaffolds);
+        // 3. User scaffolds (~/.b2c/scaffolds/)
+        const userScaffoldsDir = path.join(os.homedir(), '.b2c', 'scaffolds');
+        const userScaffolds = await discoverScaffoldsFromDir(userScaffoldsDir, 'user');
+        allScaffolds.push(...userScaffolds);
+        // 4. Project scaffolds (.b2c/scaffolds/) - highest priority
+        if (options.projectRoot) {
+            const projectScaffoldsDir = path.join(options.projectRoot, '.b2c', 'scaffolds');
+            const projectScaffolds = await discoverScaffoldsFromDir(projectScaffoldsDir, 'project');
+            allScaffolds.push(...projectScaffolds);
+        }
+        // 5. Run 'after' providers
+        const afterProviders = this.providers.filter((p) => p.priority === 'after');
+        for (const provider of afterProviders) {
+            const providerScaffolds = await provider.getScaffolds(options);
+            allScaffolds.push(...providerScaffolds);
+        }
+        // Deduplicate by ID (later sources override earlier)
+        const scaffoldMap = new Map();
+        for (const scaffold of allScaffolds) {
+            scaffoldMap.set(scaffold.id, scaffold);
+        }
+        let scaffolds = Array.from(scaffoldMap.values());
+        // Apply transformers
+        for (const transformer of this.transformers) {
+            scaffolds = await Promise.all(scaffolds.map((s) => transformer.transform(s, {
+                outputDir: process.cwd(),
+                variables: {},
+                dryRun: false,
+                force: false,
+                interactive: false,
+            })));
+        }
+        // Apply filters
+        scaffolds = filterScaffolds(scaffolds, options);
+        // Sort by name
+        scaffolds.sort((a, b) => a.id.localeCompare(b.id));
+        this.scaffoldCache.set(cacheKey, scaffolds);
+        return scaffolds;
+    }
+    /**
+     * Get a specific scaffold by ID
+     * @param id - Scaffold ID
+     * @param options - Discovery options
+     * @returns Scaffold or null if not found
+     */
+    async getScaffold(id, options = {}) {
+        const scaffolds = await this.getScaffolds(options);
+        return scaffolds.find((s) => s.id === id) || null;
+    }
+    /**
+     * Search scaffolds by query
+     * @param query - Search query
+     * @param options - Additional discovery options
+     * @returns Matching scaffolds
+     */
+    async searchScaffolds(query, options = {}) {
+        return this.getScaffolds({ ...options, query });
+    }
+}
+/**
+ * Create a new scaffold registry instance
+ */
+export function createScaffoldRegistry() {
+    return new ScaffoldRegistry();
+}
+//# sourceMappingURL=registry.js.map

package/dist/cjs/scaffold/registry.js.map

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

package/dist/cjs/scaffold/sources.d.ts

@@ -0,0 +1,45 @@
+import type { B2CInstance } from '../instance/index.js';
+import type { ScaffoldChoice, DynamicParameterSource, SourceResult } from './types.js';
+/**
+ * Common B2C Commerce hook extension points.
+ */
+export declare const HOOK_POINTS: ScaffoldChoice[];
+/**
+ * Resolve a local (non-remote) parameter source.
+ * Does not require authentication.
+ *
+ * @param source - The source type to resolve
+ * @param projectRoot - Project root directory for cartridge discovery
+ * @returns Resolved choices and optional path mapping
+ */
+export declare function resolveLocalSource(source: DynamicParameterSource, projectRoot: string): SourceResult;
+/**
+ * Resolve a remote parameter source.
+ * Requires authenticated B2CInstance (follows SDK operation pattern).
+ *
+ * @param source - The source type
+ * @param instance - Authenticated B2C instance
+ * @returns Promise resolving to choices array
+ * @throws Error if API call fails
+ */
+export declare function resolveRemoteSource(source: DynamicParameterSource, instance: B2CInstance): Promise<ScaffoldChoice[]>;
+/**
+ * Check if a source requires remote API access.
+ *
+ * @param source - The source type to check
+ * @returns True if the source requires remote access
+ */
+export declare function isRemoteSource(source: DynamicParameterSource): boolean;
+/**
+ * Validate a value against a dynamic source (local only).
+ * Used for non-interactive validation of provided values.
+ *
+ * @param source - The source type
+ * @param value - The value to validate
+ * @param projectRoot - Project root for local sources
+ * @returns Object with valid status and available choices if invalid
+ */
+export declare function validateAgainstSource(source: DynamicParameterSource, value: string, projectRoot: string): {
+    valid: boolean;
+    availableChoices?: string[];
+};

package/dist/cjs/scaffold/sources.js

@@ -0,0 +1,113 @@
+/*
+ * 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 { findCartridges } from '../operations/code/cartridges.js';
+/**
+ * Common B2C Commerce hook extension points.
+ */
+export const HOOK_POINTS = [
+    { value: 'dw.order.calculate', label: 'Order Calculate' },
+    { value: 'dw.order.calculateShipping', label: 'Calculate Shipping' },
+    { value: 'dw.order.createOrder', label: 'Create Order' },
+    { value: 'dw.order.afterPOST', label: 'OCAPI Order afterPOST' },
+    { value: 'dw.order.beforePOST', label: 'OCAPI Order beforePOST' },
+    { value: 'dw.ocapi.shop.basket.afterPOST', label: 'OCAPI Basket afterPOST' },
+    { value: 'dw.ocapi.shop.basket.modifyGETResponse', label: 'OCAPI Basket modifyGET' },
+    { value: 'dw.ocapi.shop.order.afterPOST', label: 'OCAPI Shop Order afterPOST' },
+    { value: 'dw.ocapi.shop.order.beforePOST', label: 'OCAPI Shop Order beforePOST' },
+    { value: 'dw.ocapi.data.order.afterPATCH', label: 'OCAPI Data Order afterPATCH' },
+    { value: 'dw.customer.registration', label: 'Customer Registration' },
+    { value: 'dw.customer.afterCreate', label: 'Customer afterCreate' },
+    { value: 'app.payment.processor', label: 'Payment Processor' },
+    { value: 'app.payment.form.processor', label: 'Payment Form Processor' },
+    { value: 'dw.system.request.onSession', label: 'On Session' },
+    { value: 'dw.extensions.csv.onFileProcess', label: 'CSV File Process' },
+];
+/**
+ * Resolve a local (non-remote) parameter source.
+ * Does not require authentication.
+ *
+ * @param source - The source type to resolve
+ * @param projectRoot - Project root directory for cartridge discovery
+ * @returns Resolved choices and optional path mapping
+ */
+export function resolveLocalSource(source, projectRoot) {
+    switch (source) {
+        case 'cartridges': {
+            const cartridges = findCartridges(projectRoot);
+            const pathMap = new Map(cartridges.map((c) => [c.name, c.src]));
+            return {
+                choices: cartridges.map((c) => ({ value: c.name, label: c.name })),
+                pathMap,
+            };
+        }
+        case 'hook-points': {
+            return { choices: HOOK_POINTS };
+        }
+        default: {
+            return { choices: [] };
+        }
+    }
+}
+/**
+ * Resolve a remote parameter source.
+ * Requires authenticated B2CInstance (follows SDK operation pattern).
+ *
+ * @param source - The source type
+ * @param instance - Authenticated B2C instance
+ * @returns Promise resolving to choices array
+ * @throws Error if API call fails
+ */
+export async function resolveRemoteSource(source, instance) {
+    switch (source) {
+        case 'sites': {
+            const { data, error } = await instance.ocapi.GET('/sites', {
+                params: { query: { select: '(**)' } },
+            });
+            if (error) {
+                throw new Error('Failed to fetch sites from B2C instance');
+            }
+            const sites = data;
+            return (sites.data ?? []).map((s) => ({
+                value: s.id ?? '',
+                label: s.display_name?.default || s.id || '',
+            }));
+        }
+        default: {
+            return [];
+        }
+    }
+}
+/**
+ * Check if a source requires remote API access.
+ *
+ * @param source - The source type to check
+ * @returns True if the source requires remote access
+ */
+export function isRemoteSource(source) {
+    return source === 'sites';
+}
+/**
+ * Validate a value against a dynamic source (local only).
+ * Used for non-interactive validation of provided values.
+ *
+ * @param source - The source type
+ * @param value - The value to validate
+ * @param projectRoot - Project root for local sources
+ * @returns Object with valid status and available choices if invalid
+ */
+export function validateAgainstSource(source, value, projectRoot) {
+    if (source === 'cartridges') {
+        const { choices } = resolveLocalSource(source, projectRoot);
+        const valid = choices.some((c) => c.value === value);
+        return {
+            valid,
+            availableChoices: valid ? undefined : choices.map((c) => c.value),
+        };
+    }
+    // For hook-points and other sources, no validation (allow any value)
+    return { valid: true };
+}
+//# sourceMappingURL=sources.js.map

package/dist/cjs/scaffold/sources.js.map

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

package/dist/cjs/scaffold/types.d.ts

@@ -0,0 +1,280 @@
+/**
+ * Path to the built-in scaffolds data directory
+ */
+export declare const SCAFFOLDS_DATA_DIR: string;
+/**
+ * Scaffold category. Built-in scaffolds use 'cartridge', but custom scaffolds
+ * can define their own categories.
+ */
+export type ScaffoldCategory = string;
+/**
+ * Parameter types supported by scaffold parameters
+ */
+export type ScaffoldParameterType = 'string' | 'boolean' | 'choice' | 'multi-choice';
+/**
+ * Dynamic sources for populating parameter choices at runtime.
+ *
+ * - `cartridges`: Discovers cartridges in project via .project files
+ * - `hook-points`: Static list of common hook extension points
+ * - `sites`: Remote - fetches sites from connected B2C instance
+ */
+export type DynamicParameterSource = 'cartridges' | 'hook-points' | 'sites';
+/**
+ * Overwrite behavior for generated files
+ */
+export type OverwriteBehavior = 'never' | 'always' | 'prompt' | 'merge';
+/**
+ * Choice option for choice/multi-choice parameters
+ */
+export interface ScaffoldChoice {
+    /** The value to use when this choice is selected */
+    value: string;
+    /** Human-readable label for this choice */
+    label: string;
+}
+/**
+ * Parameter definition for scaffold prompts and flags
+ */
+export interface ScaffoldParameter {
+    /** Parameter name (camelCase), used in templates as variable name */
+    name: string;
+    /** Prompt message shown in interactive mode */
+    prompt: string;
+    /** Type of the parameter */
+    type: ScaffoldParameterType;
+    /** Whether this parameter is required */
+    required: boolean;
+    /** Default value if not provided */
+    default?: string | boolean | string[];
+    /** Regex pattern for validation (string types only) */
+    pattern?: string;
+    /** Error message shown when validation fails */
+    validationMessage?: string;
+    /** Available choices for choice/multi-choice types */
+    choices?: ScaffoldChoice[];
+    /** CLI flag name override (e.g., "--name"). If not set, uses --{paramName} */
+    flag?: string;
+    /** Conditional expression: only prompt if condition is met (e.g., "otherParam=value") */
+    when?: string;
+    /** Dynamic source for populating choices at runtime */
+    source?: DynamicParameterSource;
+}
+/**
+ * File mapping from template to destination
+ */
+export interface FileMapping {
+    /** Template file path relative to the scaffold's files/ directory */
+    template: string;
+    /** Destination path (supports {{variable}} substitution) */
+    destination: string;
+    /** Conditional expression: only generate if truthy */
+    condition?: string;
+    /** Overwrite behavior for existing files */
+    overwrite?: OverwriteBehavior;
+}
+/**
+ * File modification definition for modifying existing files
+ */
+export interface FileModification {
+    /** Target file path (supports {{variable}} substitution) */
+    target: string;
+    /** Type of modification */
+    type: 'json-merge' | 'insert-after' | 'insert-before' | 'append' | 'prepend';
+    /** Content to insert/merge (for text modifications) */
+    content?: string;
+    /** Template file for the content */
+    contentTemplate?: string;
+    /** Marker string to find (for insert-after/insert-before) */
+    marker?: string;
+    /** JSON path for json-merge operations (e.g., "scripts") */
+    jsonPath?: string;
+    /** Conditional expression */
+    condition?: string;
+}
+/**
+ * Scaffold manifest (scaffold.json)
+ */
+export interface ScaffoldManifest {
+    /** Unique identifier (kebab-case) */
+    name: string;
+    /** Human-readable display name */
+    displayName: string;
+    /** Description of what this scaffold creates */
+    description: string;
+    /** Category for filtering and organization */
+    category: ScaffoldCategory;
+    /** Parameters for user input (prompts/flags) */
+    parameters: ScaffoldParameter[];
+    /** File mappings (optional - defaults to all files in files/ directory) */
+    files?: FileMapping[];
+    /** Modifications to existing files (optional) */
+    modifications?: FileModification[];
+    /** Instructions to show after generation */
+    postInstructions?: string;
+    /** Default output directory relative to cwd (created if needed) */
+    defaultOutputDir?: string;
+}
+/**
+ * Resolved scaffold with full paths and source information
+ */
+export interface Scaffold {
+    /** Unique identifier */
+    id: string;
+    /** The manifest definition */
+    manifest: ScaffoldManifest;
+    /** Full path to the scaffold directory */
+    path: string;
+    /** Full path to the files/ directory within the scaffold */
+    filesPath: string;
+    /** Source of this scaffold */
+    source: ScaffoldSource;
+}
+/**
+ * Source/origin of a scaffold
+ */
+export type ScaffoldSource = 'built-in' | 'user' | 'project' | 'plugin';
+/**
+ * Priority ordering for scaffold providers
+ */
+export type ScaffoldProviderPriority = 'before' | 'after';
+/**
+ * Options for scaffold discovery
+ */
+export interface ScaffoldDiscoveryOptions {
+    /** Filter by category */
+    category?: ScaffoldCategory;
+    /** Search query for name/description */
+    query?: string;
+    /** Include only scaffolds from specific sources */
+    sources?: ScaffoldSource[];
+    /** Project root directory (for project-local scaffolds) */
+    projectRoot?: string;
+}
+/**
+ * Scaffold provider interface for extensibility
+ */
+export interface ScaffoldProvider {
+    /** Provider name for identification */
+    readonly name: string;
+    /** Priority: 'before' runs before built-in, 'after' runs after */
+    readonly priority: ScaffoldProviderPriority;
+    /** Get scaffolds from this provider */
+    getScaffolds(options: ScaffoldDiscoveryOptions): Promise<Scaffold[]>;
+}
+/**
+ * Scaffold transformer interface for modifying scaffolds
+ */
+export interface ScaffoldTransformer {
+    /** Transformer name for identification */
+    readonly name: string;
+    /** Transform a scaffold definition */
+    transform(scaffold: Scaffold, context: ScaffoldContext): Promise<Scaffold>;
+}
+/**
+ * Context passed during scaffold operations
+ */
+export interface ScaffoldContext {
+    /** Output directory for generated files */
+    outputDir: string;
+    /** Resolved parameter values */
+    variables: Record<string, string | boolean | string[]>;
+    /** Whether running in dry-run mode */
+    dryRun: boolean;
+    /** Whether to force overwrite existing files */
+    force: boolean;
+    /** Whether running in interactive mode */
+    interactive: boolean;
+}
+/**
+ * Options for scaffold generation
+ */
+export interface ScaffoldGenerateOptions {
+    /** Output directory (defaults to cwd) */
+    outputDir?: string;
+    /** Pre-supplied variable values (from flags/env) */
+    variables?: Record<string, string | boolean | string[]>;
+    /** Preview without writing files */
+    dryRun?: boolean;
+    /** Skip prompts and overwrite existing files */
+    force?: boolean;
+    /** Enable interactive prompts (defaults to true if TTY) */
+    interactive?: boolean;
+}
+/**
+ * Result of a file generation operation
+ */
+export interface GeneratedFile {
+    /** Relative path from output directory */
+    path: string;
+    /** Absolute path to the file */
+    absolutePath: string;
+    /** Action taken */
+    action: 'created' | 'skipped' | 'overwritten' | 'merged';
+    /** Reason for skip (if action is 'skipped') */
+    skipReason?: string;
+}
+/**
+ * Result of scaffold generation
+ */
+export interface ScaffoldGenerateResult {
+    /** The scaffold that was used */
+    scaffold: Scaffold;
+    /** Files that were generated */
+    files: GeneratedFile[];
+    /** Post-generation instructions */
+    postInstructions?: string;
+    /** Whether this was a dry run */
+    dryRun: boolean;
+    /** Output directory */
+    outputDir: string;
+}
+/**
+ * Validation error for scaffold parameters
+ */
+export interface ParameterValidationError {
+    /** Parameter name */
+    parameter: string;
+    /** Error message */
+    message: string;
+    /** The invalid value */
+    value?: unknown;
+}
+/**
+ * Result of parameter validation
+ */
+export interface ParameterValidationResult {
+    /** Whether validation passed */
+    valid: boolean;
+    /** Validation errors (if any) */
+    errors: ParameterValidationError[];
+    /** Resolved parameter values */
+    values: Record<string, string | boolean | string[]>;
+}
+/**
+ * Template rendering helpers available in EJS templates
+ */
+export interface TemplateHelpers {
+    /** Convert to kebab-case */
+    kebabCase: (str: string) => string;
+    /** Convert to camelCase */
+    camelCase: (str: string) => string;
+    /** Convert to PascalCase */
+    pascalCase: (str: string) => string;
+    /** Convert to snake_case */
+    snakeCase: (str: string) => string;
+    /** Current year */
+    year: number;
+    /** Current date (YYYY-MM-DD) */
+    date: string;
+    /** Generate a UUID v4 */
+    uuid: () => string;
+}
+/**
+ * Result of resolving a dynamic parameter source.
+ */
+export interface SourceResult {
+    /** Available choices */
+    choices: ScaffoldChoice[];
+    /** For cartridges: map of name to absolute path */
+    pathMap?: Map<string, string>;
+}