sfcc-dev-mcp 1.0.15 → 1.0.19

package/src/clients/cartridge/cartridge-generation-client.ts

@@ -0,0 +1,302 @@
+/**
+ * SFCC Cartridge Generation Client
+ *
+ * Handles generation of SFCC cartridge directory structures.
+ * Templates are delegated to cartridge-templates.ts for better separation of concerns.
+ */
+
+import { Logger } from '../../utils/logger.js';
+import { IFileSystemService, IPathService } from '../../services/index.js';
+import { createCartridgeTemplates, CartridgeTemplates } from './cartridge-templates.js';
+import { CARTRIDGE_DIRECTORIES } from './cartridge-structure.js';
+
+export interface CartridgeGenerationOptions {
+  cartridgeName: string;
+  targetPath?: string;
+  fullProjectSetup?: boolean;
+}
+
+export interface CartridgeGenerationResult {
+  success: boolean;
+  message: string;
+  createdFiles: string[];
+  createdDirectories: string[];
+  skippedFiles: string[];
+}
+
+export class CartridgeGenerationClient {
+  private readonly logger: Logger;
+  private readonly templates: CartridgeTemplates;
+  private readonly fileSystem: IFileSystemService;
+  private readonly pathService: IPathService;
+
+  constructor(fileSystem: IFileSystemService, pathService: IPathService) {
+    this.logger = Logger.getChildLogger('CartridgeGenerationClient');
+    this.fileSystem = fileSystem;
+    this.pathService = pathService;
+    this.templates = createCartridgeTemplates();
+  }
+
+  /**
+   * Generate a complete cartridge structure
+   */
+  async generateCartridgeStructure(options: CartridgeGenerationOptions): Promise<CartridgeGenerationResult> {
+    const { cartridgeName, targetPath, fullProjectSetup = true } = options;
+    const createdFiles: string[] = [];
+    const createdDirectories: string[] = [];
+    const skippedFiles: string[] = [];
+
+    // Validate cartridge name to prevent directory traversal and command injection
+    if (!cartridgeName || cartridgeName.trim().length === 0) {
+      return {
+        success: false,
+        message: 'Cartridge name is required',
+        createdFiles,
+        createdDirectories,
+        skippedFiles,
+      };
+    }
+
+    // Cartridge names must be valid directory names without path separators or special characters
+    const sanitizedName = cartridgeName.trim();
+    if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(sanitizedName)) {
+      return {
+        success: false,
+        message: 'Invalid cartridge name. Must start with a letter and contain only alphanumeric characters, underscores, and dashes.',
+        createdFiles,
+        createdDirectories,
+        skippedFiles,
+      };
+    }
+
+    // Prevent path traversal in cartridge name
+    if (sanitizedName.includes('..') || sanitizedName.includes('/') || sanitizedName.includes('\\')) {
+      return {
+        success: false,
+        message: 'Invalid cartridge name. Path traversal attempts are not allowed.',
+        createdFiles,
+        createdDirectories,
+        skippedFiles,
+      };
+    }
+
+    // Limit cartridge name length
+    if (sanitizedName.length > 64) {
+      return {
+        success: false,
+        message: 'Cartridge name too long. Maximum 64 characters allowed.',
+        createdFiles,
+        createdDirectories,
+        skippedFiles,
+      };
+    }
+
+    try {
+      this.logger.info(`Starting cartridge generation for: ${sanitizedName}`);
+
+      // Validate and normalize target path
+      const rawTargetPath = targetPath ?? process.cwd();
+
+      // Prevent null byte injection in target path
+      if (rawTargetPath.includes('\0') || rawTargetPath.includes('\x00')) {
+        return {
+          success: false,
+          message: 'Invalid target path. Contains invalid characters.',
+          createdFiles,
+          createdDirectories,
+          skippedFiles,
+        };
+      }
+
+      const workingDir = this.normalizeTargetPath(rawTargetPath);
+
+      if (fullProjectSetup) {
+        return this.createFullProjectSetup(workingDir, sanitizedName, createdFiles, createdDirectories, skippedFiles);
+      }
+
+      return this.addCartridgeToExistingProject(
+        workingDir, sanitizedName, createdFiles, createdDirectories, skippedFiles,
+      );
+    } catch (error) {
+      this.logger.error('Error generating cartridge structure:', error);
+      return {
+        success: false,
+        message: `Failed to generate cartridge structure: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        createdFiles,
+        createdDirectories,
+        skippedFiles,
+      };
+    }
+  }
+
+  /**
+   * Create full project setup with root files and cartridge structure
+   */
+  private async createFullProjectSetup(
+    workingDir: string,
+    cartridgeName: string,
+    createdFiles: string[],
+    createdDirectories: string[],
+    skippedFiles: string[],
+  ): Promise<CartridgeGenerationResult> {
+    this.logger.info(`Creating full project setup directly in: ${workingDir}`);
+
+    await this.ensureDirectory(workingDir);
+    if (!createdDirectories.includes(workingDir)) {
+      createdDirectories.push(workingDir);
+    }
+
+    await this.createRootFiles(workingDir, cartridgeName, createdFiles, skippedFiles);
+    await this.createCartridgeStructure(workingDir, cartridgeName, createdFiles, createdDirectories, skippedFiles);
+
+    return {
+      success: true,
+      message: `Successfully created full project setup for cartridge '${cartridgeName}' in '${workingDir}'`,
+      createdFiles,
+      createdDirectories,
+      skippedFiles,
+    };
+  }
+
+  /**
+   * Add cartridge to existing project structure
+   */
+  private async addCartridgeToExistingProject(
+    workingDir: string,
+    cartridgeName: string,
+    createdFiles: string[],
+    createdDirectories: string[],
+    skippedFiles: string[],
+  ): Promise<CartridgeGenerationResult> {
+    const cartridgesDir = this.pathService.join(workingDir, 'cartridges');
+
+    await this.ensureDirectory(cartridgesDir);
+    if (!createdDirectories.includes(cartridgesDir)) {
+      createdDirectories.push(cartridgesDir);
+    }
+
+    await this.createCartridgeStructure(workingDir, cartridgeName, createdFiles, createdDirectories, skippedFiles);
+
+    return {
+      success: true,
+      message: `Successfully created cartridge '${cartridgeName}' in existing project at '${workingDir}'`,
+      createdFiles,
+      createdDirectories,
+      skippedFiles,
+    };
+  }
+
+  /**
+   * Normalize the target path by removing /cartridges suffix
+   */
+  private normalizeTargetPath(targetPath: string): string {
+    let normalized = targetPath.replace(/\/+$/, '');
+
+    if (normalized.endsWith('/cartridges')) {
+      normalized = normalized.slice(0, -11);
+    }
+
+    this.logger.debug(`Normalized target path from '${targetPath}' to '${normalized}'`);
+    return normalized;
+  }
+
+  /**
+   * Create root project files (package.json, webpack, etc.)
+   */
+  private async createRootFiles(
+    projectDir: string,
+    cartridgeName: string,
+    createdFiles: string[],
+    skippedFiles: string[],
+  ): Promise<void> {
+    const filesToCreate = [
+      { name: 'package.json', content: JSON.stringify(this.templates.packageJson(cartridgeName), null, 2) },
+      { name: 'dw.json', content: JSON.stringify(this.templates.dwJson(), null, 2) },
+      { name: 'webpack.config.js', content: this.templates.webpackConfig(cartridgeName) },
+      { name: '.eslintrc.json', content: JSON.stringify(this.templates.eslintrc(), null, 2) },
+      { name: '.stylelintrc.json', content: JSON.stringify(this.templates.stylelintrc(), null, 2) },
+      { name: '.eslintignore', content: this.templates.eslintignore() },
+      { name: '.gitignore', content: this.templates.gitignore() },
+    ];
+
+    for (const file of filesToCreate) {
+      const filePath = this.pathService.join(projectDir, file.name);
+      await this.safeWriteFile(filePath, file.content, createdFiles, skippedFiles);
+    }
+  }
+
+  /**
+   * Create the cartridge directory structure
+   */
+  private async createCartridgeStructure(
+    baseDir: string,
+    cartridgeName: string,
+    createdFiles: string[],
+    createdDirectories: string[],
+    skippedFiles: string[],
+  ): Promise<void> {
+    // Create cartridges directory
+    const cartridgesDir = this.pathService.join(baseDir, 'cartridges');
+    await this.ensureDirectory(cartridgesDir);
+    createdDirectories.push(cartridgesDir);
+
+    // Create specific cartridge directory
+    const cartridgeDir = this.pathService.join(cartridgesDir, cartridgeName);
+    await this.ensureDirectory(cartridgeDir);
+    createdDirectories.push(cartridgeDir);
+
+    // Create .project file
+    const projectPath = this.pathService.join(cartridgeDir, '.project');
+    await this.safeWriteFile(projectPath, this.templates.dotProject(cartridgeName), createdFiles, skippedFiles);
+
+    // Create cartridge subdirectory
+    const cartridgeSubDir = this.pathService.join(cartridgeDir, 'cartridge');
+    await this.ensureDirectory(cartridgeSubDir);
+    createdDirectories.push(cartridgeSubDir);
+
+    // Create cartridge properties file
+    const propertiesPath = this.pathService.join(cartridgeSubDir, `${cartridgeName}.properties`);
+    await this.safeWriteFile(
+      propertiesPath, this.templates.projectProperties(cartridgeName), createdFiles, skippedFiles,
+    );
+
+    // Create directory structure from constants
+    for (const dir of CARTRIDGE_DIRECTORIES) {
+      const fullPath = this.pathService.join(cartridgeSubDir, dir);
+      await this.ensureDirectory(fullPath);
+      createdDirectories.push(fullPath);
+    }
+  }
+
+  /**
+   * Ensure a directory exists, create if it doesn't
+   */
+  private async ensureDirectory(dirPath: string): Promise<void> {
+    try {
+      await this.fileSystem.access(dirPath);
+    } catch {
+      await this.fileSystem.mkdir(dirPath, { recursive: true });
+      this.logger.info(`Created directory: ${dirPath}`);
+    }
+  }
+
+  /**
+   * Safely write a file, skipping if it already exists
+   */
+  private async safeWriteFile(
+    filePath: string,
+    content: string,
+    createdFiles: string[],
+    skippedFiles: string[],
+  ): Promise<void> {
+    try {
+      await this.fileSystem.access(filePath);
+      skippedFiles.push(filePath);
+      this.logger.info(`Skipped existing file: ${filePath}`);
+    } catch {
+      await this.fileSystem.writeFile(filePath, content);
+      createdFiles.push(filePath);
+      this.logger.info(`Created file: ${filePath}`);
+    }
+  }
+}

package/src/clients/cartridge/cartridge-structure.ts

@@ -0,0 +1,37 @@
+/**
+ * Cartridge Directory Structure
+ *
+ * Defines the directory structure for SFCC cartridges.
+ * Separated from the main client for better maintainability.
+ */
+
+/**
+ * Standard cartridge subdirectories to create
+ */
+export const CARTRIDGE_DIRECTORIES = [
+  'controllers',
+  'models',
+  'templates',
+  'templates/default',
+  'templates/resources',
+  'client',
+  'client/default',
+  'client/default/js',
+  'client/default/scss',
+] as const;
+
+/**
+ * Root project files to create
+ */
+export const ROOT_PROJECT_FILES = [
+  'package.json',
+  'dw.json',
+  'webpack.config.js',
+  '.eslintrc.json',
+  '.stylelintrc.json',
+  '.eslintignore',
+  '.gitignore',
+] as const;
+
+export type CartridgeDirectory = typeof CARTRIDGE_DIRECTORIES[number];
+export type RootProjectFile = typeof ROOT_PROJECT_FILES[number];

package/src/clients/cartridge/cartridge-templates.ts

@@ -0,0 +1,246 @@
+/**
+ * Cartridge File Templates
+ *
+ * Contains all template generators for SFCC cartridge file generation.
+ * Separated from the main client for better maintainability and testability.
+ */
+
+export interface CartridgeTemplates {
+  packageJson: (cartridgeName: string) => object;
+  dwJson: () => object;
+  webpackConfig: (cartridgeName: string) => string;
+  dotProject: (cartridgeName: string) => string;
+  projectProperties: (cartridgeName: string) => string;
+  eslintrc: () => object;
+  stylelintrc: () => object;
+  eslintignore: () => string;
+  gitignore: () => string;
+}
+
+/**
+ * Creates the complete set of cartridge templates
+ */
+export function createCartridgeTemplates(): CartridgeTemplates {
+  return {
+    packageJson: createPackageJsonTemplate,
+    dwJson: createDwJsonTemplate,
+    webpackConfig: createWebpackConfigTemplate,
+    dotProject: createDotProjectTemplate,
+    projectProperties: createProjectPropertiesTemplate,
+    eslintrc: createEslintrcTemplate,
+    stylelintrc: createStylelintrcTemplate,
+    eslintignore: createEslintignoreTemplate,
+    gitignore: createGitignoreTemplate,
+  };
+}
+
+function createPackageJsonTemplate(cartridgeName: string): object {
+  return {
+    name: cartridgeName,
+    version: '0.0.1',
+    description: 'New overlay cartridge',
+    main: 'index.js',
+    scripts: {
+      'lint': 'npm run lint:css && npm run lint:js',
+      'lint:css': 'sgmf-scripts --lint css',
+      'lint:js': 'sgmf-scripts --lint js',
+      'lint:fix': 'eslint cartridges --fix',
+      upload: 'sgmf-scripts --upload -- ',
+      uploadCartridge: `sgmf-scripts --uploadCartridge ${cartridgeName}`,
+      'compile:js': 'sgmf-scripts --compile js',
+      'compile:scss': 'sgmf-scripts --compile css',
+    },
+    devDependencies: {
+      autoprefixer: '^10.4.14',
+      bestzip: '^2.2.1',
+      'css-loader': '^6.0.0',
+      'css-minimizer-webpack-plugin': '^5.0.1',
+      eslint: '^8.56.0',
+      'eslint-config-airbnb-base': '^15.0.0',
+      'eslint-config-prettier': '^9.1.0',
+      'eslint-plugin-import': '^2.29.0',
+      'mini-css-extract-plugin': '^2.7.6',
+      'postcss-loader': '^7.0.0',
+      sass: '^1.69.7',
+      'sass-loader': '^13.3.2',
+      'sgmf-scripts': '^3.0.0',
+      shx: '^0.3.4',
+      stylelint: '^15.4.0',
+      'stylelint-config-standard-scss': '^11.0.0',
+      'webpack-remove-empty-scripts': '^1.0.4',
+    },
+    browserslist: [
+      'last 2 versions',
+      'ie >= 10',
+    ],
+  };
+}
+
+function createDwJsonTemplate(): object {
+  return {
+    hostname: '',
+    username: '',
+    password: '',
+    'code-version': '',
+  };
+}
+
+function createWebpackConfigTemplate(cartridgeName: string): string {
+  return `'use strict';
+
+var path = require('path');
+var MiniCssExtractPlugin = require('mini-css-extract-plugin');
+var CssMinimizerPlugin = require('css-minimizer-webpack-plugin');
+var sgmfScripts = require('sgmf-scripts');
+var RemoveEmptyScriptsPlugin = require('webpack-remove-empty-scripts');
+
+module.exports = [{
+    mode: 'development',
+    name: 'js',
+    entry: sgmfScripts.createJsPath(),
+    output: {
+        path: path.resolve('./cartridges/${cartridgeName}/cartridge/static'),
+        filename: '[name].js'
+    }
+}, {
+    mode: 'none',
+    name: 'scss',
+    entry: sgmfScripts.createScssPath(),
+    output: {
+        path: path.resolve('./cartridges/${cartridgeName}/cartridge/static')
+    },
+    module: {
+        rules: [{
+            test: /\\.scss$/,
+            use: [{
+                loader: MiniCssExtractPlugin.loader,
+                options: {
+                    esModule: false
+                }
+            },
+            {
+                loader: 'css-loader',
+                options: {
+                    url: false
+                }
+            }, {
+                loader: 'postcss-loader',
+                options: {
+                    postcssOptions: {
+                        plugins: [require('autoprefixer')]
+                    }
+                }
+            }, {
+                loader: 'sass-loader',
+                options: {
+                    implementation: require('sass'),
+                    sassOptions: {
+                        includePaths: [
+                            path.resolve(path.resolve(process.cwd(), '../storefront-reference-architecture/node_modules/')),
+                            path.resolve(process.cwd(), '../storefront-reference-architecture/node_modules/flag-icons/sass')
+                        ]
+                    }
+                }
+            }]
+        }]
+    },
+    plugins: [
+        new RemoveEmptyScriptsPlugin(),
+        new MiniCssExtractPlugin({
+            filename: '[name].css',
+            chunkFilename: '[name].css'
+        })
+    ],
+    optimization: {
+        minimizer: ['...', new CssMinimizerPlugin()]
+    }
+}];`;
+}
+
+function createDotProjectTemplate(cartridgeName: string): string {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+    <name>${cartridgeName}</name>
+    <comment></comment>
+    <projects>
+    </projects>
+    <buildSpec>
+        <buildCommand>
+            <name>com.demandware.studio.core.beehiveElementBuilder</name>
+            <arguments>
+            </arguments>
+        </buildCommand>
+    </buildSpec>
+    <natures>
+        <nature>com.demandware.studio.core.beehiveNature</nature>
+    </natures>
+</projectDescription>`;
+}
+
+function createProjectPropertiesTemplate(cartridgeName: string): string {
+  return `## cartridge.properties for cartridge ${cartridgeName}
+#demandware.cartridges.${cartridgeName}.multipleLanguageStorefront=true`;
+}
+
+function createEslintrcTemplate(): object {
+  return {
+    root: true,
+    extends: 'airbnb-base/legacy',
+    globals: {
+      session: 'readonly',
+      request: 'readonly',
+    },
+    rules: {
+      'import/no-unresolved': 'off',
+      indent: ['error', 4, { SwitchCase: 1, VariableDeclarator: 1 }],
+      'func-names': 'off',
+      'require-jsdoc': 'error',
+      'valid-jsdoc': ['error', {
+        preferType: {
+          Boolean: 'boolean',
+          Number: 'number',
+          object: 'Object',
+          String: 'string',
+        },
+        requireReturn: false,
+      }],
+      'vars-on-top': 'off',
+      'global-require': 'off',
+      'no-shadow': ['error', { allow: ['err', 'callback'] }],
+      'max-len': 'off',
+      'no-plusplus': 'off',
+    },
+  };
+}
+
+function createStylelintrcTemplate(): object {
+  return {
+    extends: 'stylelint-config-standard-scss',
+    plugins: [
+      'stylelint-scss',
+    ],
+  };
+}
+
+function createEslintignoreTemplate(): string {
+  return `node_modules/
+cartridges/**/cartridge/static/
+coverage/
+doc/
+bin/
+codecept.conf.js`;
+}
+
+function createGitignoreTemplate(): string {
+  return `node_modules/
+cartridges/*/cartridge/static/
+.DS_Store
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+coverage/
+.nyc_output/
+.env
+dw.json`;
+}

package/src/clients/cartridge/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Cartridge Module Exports
+ */
+export { CartridgeGenerationClient } from './cartridge-generation-client.js';
+export { createCartridgeTemplates, type CartridgeTemplates } from './cartridge-templates.js';
+export { CARTRIDGE_DIRECTORIES, ROOT_PROJECT_FILES } from './cartridge-structure.js';