@sfdc-webapps/cli 1.0.2

package/src/utils/import-merger.ts

@@ -0,0 +1,293 @@
+import { SourceFile } from 'ts-morph';
+
+/**
+ * Merge imports from feature file into target file
+ * Handles:
+ * - Deduplicating imports from the same module
+ * - Merging named imports from the same module
+ * - Preventing duplicate default import names from different modules
+ * - Merging different import types from the same module
+ * - Removing imports from __delete__ marked files
+ */
+export function mergeImports(featureFile: SourceFile, targetFile: SourceFile): void {
+  const featureImports = featureFile.getImportDeclarations();
+  const targetImports = targetFile.getImportDeclarations();
+
+  // Build a map of existing target imports by module specifier
+  // This handles multiple imports from the same module in the target
+  const targetImportsMap = new Map<string, typeof targetImports[0]>();
+  const duplicateTargetImports: typeof targetImports = [];
+
+  for (const imp of targetImports) {
+    const moduleSpecifier = imp.getModuleSpecifierValue();
+
+    if (!targetImportsMap.has(moduleSpecifier)) {
+      targetImportsMap.set(moduleSpecifier, imp);
+    } else {
+      // Found a duplicate import from same module, mark for merging
+      duplicateTargetImports.push(imp);
+    }
+  }
+
+  // Merge duplicate imports in target first
+  for (const duplicateImport of duplicateTargetImports) {
+    const moduleSpecifier = duplicateImport.getModuleSpecifierValue();
+    const primaryImport = targetImportsMap.get(moduleSpecifier);
+
+    if (primaryImport) {
+      mergeImportDeclarations(duplicateImport, primaryImport);
+      duplicateImport.remove();
+    }
+  }
+
+  // Track all default import names already in target (to prevent conflicts)
+  const existingDefaultImportNames = new Set<string>();
+  for (const imp of targetFile.getImportDeclarations()) {
+    const defaultImport = imp.getDefaultImport();
+    if (defaultImport) {
+      existingDefaultImportNames.add(defaultImport.getText());
+    }
+  }
+
+  // Add/merge imports from feature
+  for (const featureImport of featureImports) {
+    const moduleSpecifier = featureImport.getModuleSpecifierValue();
+    const targetImport = targetImportsMap.get(moduleSpecifier);
+    const featureDefaultImport = featureImport.getDefaultImport()?.getText();
+
+    if (!targetImport) {
+      // Import from this module doesn't exist in target
+      // Check if default import name would conflict
+      if (featureDefaultImport && existingDefaultImportNames.has(featureDefaultImport)) {
+        // Feature import has same name as existing import from different module
+        // Feature should take precedence - find and replace the conflicting import
+        const conflictingImport = targetFile.getImportDeclarations().find(imp =>
+          imp.getDefaultImport()?.getText() === featureDefaultImport &&
+          imp.getModuleSpecifierValue() !== moduleSpecifier
+        );
+
+        if (conflictingImport) {
+          // Replace the module specifier of the conflicting import
+          conflictingImport.setModuleSpecifier(moduleSpecifier);
+
+          // Merge any named imports from feature into the updated import
+          const featureNamedImports = featureImport.getNamedImports();
+          if (featureNamedImports.length > 0) {
+            const existingNamedImports = new Set(
+              conflictingImport.getNamedImports().map(ni => ni.getName())
+            );
+            for (const namedImport of featureNamedImports) {
+              const importName = namedImport.getName();
+              if (!existingNamedImports.has(importName)) {
+                conflictingImport.addNamedImport({
+                  name: importName,
+                  alias: namedImport.getAliasNode()?.getText()
+                });
+              }
+            }
+          }
+
+          // Update the map to point to the updated import
+          targetImportsMap.set(moduleSpecifier, conflictingImport);
+          continue;
+        }
+      }
+
+      // Add the import
+      targetFile.addImportDeclaration({
+        moduleSpecifier: moduleSpecifier,
+        isTypeOnly: featureImport.isTypeOnly(),
+        namedImports: featureImport.getNamedImports().map(ni => ({
+          name: ni.getName(),
+          alias: ni.getAliasNode()?.getText(),
+          isTypeOnly: ni.isTypeOnly()
+        })),
+        defaultImport: featureDefaultImport,
+        namespaceImport: featureImport.getNamespaceImport()?.getText()
+      });
+
+      // Track the new default import
+      if (featureDefaultImport) {
+        existingDefaultImportNames.add(featureDefaultImport);
+      }
+      // Update map with new import
+      const newImports = targetFile.getImportDeclarations();
+      const addedImport = newImports[newImports.length - 1];
+      targetImportsMap.set(moduleSpecifier, addedImport);
+    } else {
+      // Import from this module exists, merge them
+      mergeImportDeclarations(featureImport, targetImport);
+    }
+  }
+
+  // Final deduplication pass for named imports
+  deduplicateNamedImports(targetFile);
+
+  // Remove imports from __delete__ marked files
+  removeDeleteMarkedImports(targetFile);
+
+  // Ensure proper formatting: blank line after imports
+  ensureBlankLineAfterImports(targetFile);
+
+  // Don't call organizeImports() as it can be too aggressive and remove imports
+  // that are actually needed but appear unused in the isolated file context
+}
+
+/**
+ * Merge sourceImport into targetImport
+ * Combines default imports, named imports, and namespace imports
+ * Handles type imports vs regular imports appropriately
+ */
+function mergeImportDeclarations(
+  sourceImport: ReturnType<SourceFile['getImportDeclarations']>[0],
+  targetImport: ReturnType<SourceFile['getImportDeclarations']>[0]
+): void {
+  const sourceIsTypeOnly = sourceImport.isTypeOnly();
+  const targetIsTypeOnly = targetImport.isTypeOnly();
+
+  // If type-only status differs, we need to add a separate import declaration
+  // instead of merging, because you can't mix type and regular imports
+  if (sourceIsTypeOnly !== targetIsTypeOnly) {
+    // Get the source file and add a new import
+    const targetFile = targetImport.getSourceFile();
+    const moduleSpecifier = sourceImport.getModuleSpecifierValue();
+
+    // Check if an import with matching type-only status already exists
+    const existingMatchingImport = targetFile.getImportDeclarations().find(imp =>
+      imp.getModuleSpecifierValue() === moduleSpecifier &&
+      imp.isTypeOnly() === sourceIsTypeOnly &&
+      imp !== targetImport
+    );
+
+    if (existingMatchingImport) {
+      // Merge into the matching import instead
+      mergeImportDeclarations(sourceImport, existingMatchingImport);
+      return;
+    }
+
+    // Add new import with same type-only status as source
+    targetFile.addImportDeclaration({
+      moduleSpecifier: moduleSpecifier,
+      isTypeOnly: sourceIsTypeOnly,
+      namedImports: sourceImport.getNamedImports().map(ni => ({
+        name: ni.getName(),
+        alias: ni.getAliasNode()?.getText(),
+        isTypeOnly: ni.isTypeOnly()
+      })),
+      defaultImport: sourceImport.getDefaultImport()?.getText(),
+      namespaceImport: sourceImport.getNamespaceImport()?.getText()
+    });
+    return;
+  }
+
+  // Same type-only status, proceed with merge
+
+  // Add default import if target doesn't have one and source does
+  const sourceDefaultImport = sourceImport.getDefaultImport();
+  const targetDefaultImport = targetImport.getDefaultImport();
+
+  if (sourceDefaultImport && !targetDefaultImport) {
+    targetImport.setDefaultImport(sourceDefaultImport.getText());
+  }
+
+  // Add namespace import if target doesn't have one and source does
+  const sourceNamespaceImport = sourceImport.getNamespaceImport();
+  const targetNamespaceImport = targetImport.getNamespaceImport();
+
+  if (sourceNamespaceImport && !targetNamespaceImport) {
+    targetImport.setNamespaceImport(sourceNamespaceImport.getText());
+  }
+
+  // Merge named imports
+  const targetNamedImports = new Set(
+    targetImport.getNamedImports().map(ni => ni.getName())
+  );
+
+  for (const sourceNamedImport of sourceImport.getNamedImports()) {
+    const importName = sourceNamedImport.getName();
+    if (!targetNamedImports.has(importName)) {
+      targetImport.addNamedImport({
+        name: importName,
+        alias: sourceNamedImport.getAliasNode()?.getText(),
+        isTypeOnly: sourceNamedImport.isTypeOnly()
+      });
+    }
+  }
+}
+
+/**
+ * Remove duplicate named imports within each import declaration
+ */
+function deduplicateNamedImports(file: SourceFile): void {
+  const allImports = file.getImportDeclarations();
+
+  for (const imp of allImports) {
+    const namedImports = imp.getNamedImports();
+    const seen = new Set<string>();
+
+    for (const namedImport of namedImports) {
+      const name = namedImport.getName();
+      if (seen.has(name)) {
+        namedImport.remove();
+      } else {
+        seen.add(name);
+      }
+    }
+  }
+}
+
+/**
+ * Remove imports from files marked with __delete__ prefix
+ * These imports reference deleted files and should be removed
+ */
+function removeDeleteMarkedImports(file: SourceFile): void {
+  const DELETE_PREFIX = '__delete__';
+  const allImports = file.getImportDeclarations();
+
+  for (const imp of allImports) {
+    const moduleSpecifier = imp.getModuleSpecifierValue();
+
+    // Check if the module specifier contains __delete__ prefix
+    // This covers both direct paths like "./__delete__new" and path segments
+    if (moduleSpecifier.includes(DELETE_PREFIX)) {
+      imp.remove();
+    }
+  }
+}
+
+/**
+ * Ensure there's a blank line after the last import declaration
+ * This maintains proper formatting between imports and code
+ */
+function ensureBlankLineAfterImports(file: SourceFile): void {
+  const imports = file.getImportDeclarations();
+
+  if (imports.length === 0) {
+    return; // No imports, nothing to do
+  }
+
+  const lastImport = imports[imports.length - 1];
+
+  // Get the next statement after imports (if any)
+  const statements = file.getStatements();
+  const lastImportIndex = statements.indexOf(lastImport as any);
+
+  if (lastImportIndex === -1 || lastImportIndex === statements.length - 1) {
+    return; // Last import is the last statement, no code after it
+  }
+
+  const nextStatement = statements[lastImportIndex + 1];
+
+  // Check if there's already proper spacing
+  const fullText = file.getFullText();
+  const textBetween = fullText.substring(lastImport.getEnd(), nextStatement.getStart());
+
+  // Count newlines in the text between
+  const newlineCount = (textBetween.match(/\n/g) || []).length;
+
+  // We want at least 2 newlines (one ends the import, one creates blank line)
+  if (newlineCount < 2) {
+    // Insert additional newline after the last import
+    file.insertText(lastImport.getEnd(), '\n');
+  }
+}

package/src/utils/logger.ts

@@ -0,0 +1,21 @@
+import chalk from 'chalk';
+
+export function success(message: string): void {
+  console.log(chalk.green('✓'), message);
+}
+
+export function error(message: string): void {
+  console.error(chalk.red('✗'), message);
+}
+
+export function info(message: string): void {
+  console.log(chalk.blue('ℹ'), message);
+}
+
+export function warning(message: string): void {
+  console.log(chalk.yellow('⚠'), message);
+}
+
+export function heading(message: string): void {
+  console.log(chalk.bold.cyan(`\n${message}`));
+}

package/src/utils/path-mappings.ts

@@ -0,0 +1,154 @@
+import { PathMapping, PathMappings } from '../types.js';
+
+/**
+ * Get default path mappings for a feature
+ * Maps webApp → digitalExperiences/webApplications/<featureName>
+ *
+ * @param featureName - The name of the feature (e.g., 'feature-navigation-menu')
+ * @returns Array containing the default path mapping
+ *
+ * @example
+ * getDefaultPathMappings('feature-nav')
+ * // Returns: [{ from: 'webApp', to: 'digitalExperiences/webApplications/feature-nav' }]
+ */
+export function getDefaultPathMappings(featureName: string): PathMapping[] {
+  return [
+    {
+      from: 'webApp',
+      to: `digitalExperiences/webApplications/${featureName}`
+    }
+  ];
+}
+
+/**
+ * Check if path mappings are enabled for a feature
+ * Default: true (enabled by default, opt-out)
+ *
+ * @param pathMappings - The path mappings configuration from the feature
+ * @returns true if mappings are enabled (default), false if explicitly disabled
+ *
+ * @example
+ * arePathMappingsEnabled(undefined) // Returns: true (default enabled)
+ * arePathMappingsEnabled({ enabled: false }) // Returns: false
+ * arePathMappingsEnabled({ enabled: true }) // Returns: true
+ * arePathMappingsEnabled({ mappings: [...] }) // Returns: true (enabled by default)
+ */
+export function arePathMappingsEnabled(pathMappings?: PathMappings): boolean {
+  // If pathMappings is undefined, default to enabled
+  if (!pathMappings) return true;
+
+  // If pathMappings.enabled is explicitly set, use that value
+  if (pathMappings.enabled !== undefined) return pathMappings.enabled;
+
+  // Otherwise, enabled by default
+  return true;
+}
+
+/**
+ * Get the effective path mappings for a feature
+ * Returns custom mappings if provided, otherwise default mappings
+ *
+ * @param featureName - The name of the feature
+ * @param pathMappings - The path mappings configuration from the feature
+ * @returns Array of path mappings to apply (empty if disabled)
+ *
+ * @example
+ * // Default behavior (no config)
+ * getEffectivePathMappings('feature-nav', undefined)
+ * // Returns: [{ from: 'webApp', to: 'digitalExperiences/webApplications/feature-nav' }]
+ *
+ * // Disabled
+ * getEffectivePathMappings('feature-nav', { enabled: false })
+ * // Returns: []
+ *
+ * // Custom mappings
+ * getEffectivePathMappings('feature-nav', { mappings: [{ from: 'web', to: 'custom/path' }] })
+ * // Returns: [{ from: 'web', to: 'custom/path' }]
+ */
+export function getEffectivePathMappings(
+  featureName: string,
+  pathMappings?: PathMappings
+): PathMapping[] {
+  // If disabled, return empty array (no mappings)
+  if (!arePathMappingsEnabled(pathMappings)) {
+    return [];
+  }
+
+  // If custom mappings provided, use those
+  if (pathMappings?.mappings && pathMappings.mappings.length > 0) {
+    return pathMappings.mappings;
+  }
+
+  // Otherwise, use default mappings
+  return getDefaultPathMappings(featureName);
+}
+
+/**
+ * Apply path mappings to a template file path
+ *
+ * This function transforms simplified paths (e.g., "webApp/src/app.tsx") into
+ * their full target paths (e.g., "digitalExperiences/webApplications/feature-name/src/app.tsx")
+ * based on the provided mappings.
+ *
+ * The function checks each mapping in order and applies the first one that matches.
+ * If no mapping matches, the path is returned unchanged (backwards compatibility).
+ *
+ * @param templatePath - Path relative to template directory (e.g., "webApp/src/app.tsx")
+ * @param mappings - Array of path mappings to apply
+ * @returns Transformed path with mapping applied
+ *
+ * @example
+ * // Apply default webApp mapping
+ * applyPathMappings('webApp/src/app.tsx', [{
+ *   from: 'webApp',
+ *   to: 'digitalExperiences/webApplications/feature-nav'
+ * }])
+ * // Returns: 'digitalExperiences/webApplications/feature-nav/src/app.tsx'
+ *
+ * @example
+ * // Backwards compatibility - old paths pass through
+ * applyPathMappings('digitalExperiences/webApplications/feature-nav/src/app.tsx', [...])
+ * // Returns: 'digitalExperiences/webApplications/feature-nav/src/app.tsx'
+ *
+ * @example
+ * // No mappings - path unchanged
+ * applyPathMappings('webApp/src/app.tsx', [])
+ * // Returns: 'webApp/src/app.tsx'
+ *
+ * @example
+ * // No match - path unchanged
+ * applyPathMappings('src/app.tsx', [{ from: 'webApp', to: '...' }])
+ * // Returns: 'src/app.tsx'
+ */
+export function applyPathMappings(
+  templatePath: string,
+  mappings: PathMapping[]
+): string {
+  // If no mappings, return path as-is (backwards compatibility)
+  if (mappings.length === 0) {
+    return templatePath;
+  }
+
+  // Try each mapping in order (first match wins)
+  for (const mapping of mappings) {
+    const fromPrefix = mapping.from + '/';
+
+    // Check if path starts with the mapping's "from" prefix
+    if (templatePath.startsWith(fromPrefix)) {
+      // Replace prefix with "to" prefix
+      const remainder = templatePath.substring(fromPrefix.length);
+      return mapping.to + '/' + remainder;
+    }
+
+    // Also handle exact match (no trailing slash)
+    if (templatePath === mapping.from) {
+      return mapping.to;
+    }
+  }
+
+  // No mapping matched, return original path
+  // This handles both:
+  // 1. Old-style full paths (digitalExperiences/webApplications/...)
+  // 2. Other paths that don't use the mapping shorthand
+  return templatePath;
+}

package/src/utils/paths.ts

@@ -0,0 +1,121 @@
+import { existsSync, readFileSync } from 'fs';
+import { join, dirname, basename } from 'path';
+import { fileURLToPath } from 'url';
+
+/**
+ * Find the monorepo root by searching upward for package.json with workspaces
+ */
+export function getMonorepoRoot(): string {
+  let currentDir = dirname(fileURLToPath(import.meta.url));
+
+  while (currentDir !== '/') {
+    const packageJsonPath = join(currentDir, 'package.json');
+
+    if (existsSync(packageJsonPath)) {
+      const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+      if (packageJson.workspaces) {
+        return currentDir;
+      }
+    }
+
+    currentDir = dirname(currentDir);
+  }
+
+  throw new Error('Could not find monorepo root (package.json with workspaces)');
+}
+
+/**
+ * Get the features directory path
+ */
+export function getFeaturesDir(): string {
+  return join(getMonorepoRoot(), 'packages', 'features');
+}
+
+/**
+ * Get the directory path for a specific feature
+ */
+export function getFeatureDir(featureName: string): string {
+  return join(getFeaturesDir(), featureName);
+}
+
+/**
+ * Resolve a file path within a feature
+ */
+export function resolveFeatureFile(featureName: string, filePath: string): string {
+  return join(getFeatureDir(featureName), filePath);
+}
+
+/**
+ * Translate a feature file path to the corresponding base app path
+ * Replaces feature name with base app name in the nested structure
+ *
+ * Handles three formats:
+ * 1. Full path: "digitalExperiences/webApplications/feature-simple/src/routes.tsx"
+ *    → "digitalExperiences/webApplications/base-app/src/routes.tsx"
+ * 2. WebApp path: "webApp/src/routes.tsx"
+ *    → "digitalExperiences/webApplications/base-app/src/routes.tsx"
+ * 3. Other SFDX paths: "classes/NavMenu.cls"
+ *    → "classes/NavMenu.cls" (unchanged, stays at root)
+ */
+export function translatePathToBaseApp(featurePath: string, featureName: string, baseAppPath: string): string {
+  // Extract base app name from base app path (last directory component)
+  const baseAppName = basename(baseAppPath);
+
+  // Pattern: digitalExperiences/webApplications/<feature-name>/...
+  const prefix = 'digitalExperiences/webApplications/';
+
+  if (featurePath.startsWith(prefix)) {
+    // Full path format - remove prefix to get: <feature-name>/...
+    const remainder = featurePath.substring(prefix.length);
+
+    // Check if it starts with the feature name
+    if (remainder.startsWith(featureName + '/')) {
+      // Replace feature name with base app name
+      const pathAfterFeatureName = remainder.substring(featureName.length + 1);
+      return `${prefix}${baseAppName}/${pathAfterFeatureName}`;
+    }
+  } else if (featurePath.startsWith('webApp/')) {
+    // WebApp path - strip webApp/ prefix and add full digitalExperiences path
+    const pathAfterWebApp = featurePath.substring('webApp/'.length);
+    return `${prefix}${baseAppName}/${pathAfterWebApp}`;
+  }
+
+  // All other paths (SFDX metadata, etc.) - return as is (stays at root level)
+  return featurePath;
+}
+
+/**
+ * Translate a feature file path to use a target app name
+ * Replaces feature name with target app name in the nested structure
+ *
+ * Handles three formats:
+ * 1. Full path: "digitalExperiences/webApplications/feature-simple/src/routes.tsx"
+ *    → "digitalExperiences/webApplications/target-app/src/routes.tsx"
+ * 2. WebApp path: "webApp/src/routes.tsx"
+ *    → "digitalExperiences/webApplications/target-app/src/routes.tsx"
+ * 3. Other SFDX paths: "classes/NavMenu.cls"
+ *    → "classes/NavMenu.cls" (unchanged, stays at root)
+ */
+export function translatePathToTargetApp(featurePath: string, featureName: string, targetAppName: string): string {
+  // Pattern: digitalExperiences/webApplications/<feature-name>/...
+  const prefix = 'digitalExperiences/webApplications/';
+
+  if (featurePath.startsWith(prefix)) {
+    // Full path format - remove prefix to get: <feature-name>/...
+    const remainder = featurePath.substring(prefix.length);
+
+    // Check if it starts with the feature name
+    if (remainder.startsWith(featureName + '/')) {
+      // Replace feature name with target app name
+      const pathAfterFeatureName = remainder.substring(featureName.length + 1);
+      return `${prefix}${targetAppName}/${pathAfterFeatureName}`;
+    }
+  } else if (featurePath.startsWith('webApp/')) {
+    // WebApp path - strip webApp/ prefix and add full digitalExperiences path
+    const pathAfterWebApp = featurePath.substring('webApp/'.length);
+    return `${prefix}${targetAppName}/${pathAfterWebApp}`;
+  }
+
+  // All other paths (SFDX metadata, etc.) - return as is (stays at root level)
+  return featurePath;
+}