@sfdc-webapps/cli 1.0.2

package/src/core/file-operations.ts

@@ -0,0 +1,265 @@
+import { readFileSync, existsSync, mkdirSync, writeFileSync, rmSync, statSync } from 'fs';
+import { dirname, extname } from 'path';
+import { mergeRoutes } from '../utils/route-merger.js';
+import * as logger from '../utils/logger.js';
+
+const INHERIT_PREFIX = '__inherit__';
+
+export class FileOperationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'FileOperationError';
+  }
+}
+
+/**
+ * Fix import paths by removing __inherit__ prefix from import/require statements
+ *
+ * Examples:
+ * - import { x } from './__inherit__routes' -> import { x } from './routes'
+ * - import x from '../__inherit__routes.tsx' -> import x from '../routes.tsx'
+ * - require('./__inherit__file') -> require('./file')
+ *
+ * @param content - File content to process
+ * @returns Content with fixed import paths
+ */
+function fixInheritImportPaths(content: string): string {
+  // Match import/export statements with __inherit__ in the path
+  // Handles: import ... from '...__inherit__...'
+  //          export ... from '...__inherit__...'
+  //          import('...__inherit__...')
+  //          require('...__inherit__...')
+
+  // Pattern explanation:
+  // (from\s+|import\(|require\() - matches 'from ', 'import(', or 'require('
+  // (['"`]) - captures opening quote
+  // ([^'"`]*) - captures path before __inherit__
+  // __inherit__ - the prefix to remove
+  // ([^'"`]*) - captures rest of path
+  // \2 - matches same quote type as opening
+
+  return content.replace(
+    /(from\s+|import\(|require\()(['"`])([^'"`]*)__inherit__([^'"`]*)\2/g,
+    (match, prefix, quote, before, after) => {
+      return `${prefix}${quote}${before}${after}${quote}`;
+    }
+  );
+}
+
+/**
+ * Check if file is a JS/TS file that may contain imports
+ */
+function isJavaScriptFile(filePath: string): boolean {
+  const ext = extname(filePath);
+  return ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'].includes(ext);
+}
+
+/**
+ * Apply a file from patch to target, optionally merging with base
+ *
+ * @param patchFilePath - Full path to the patch file from the feature
+ * @param baseFilePath - Full path to the original base app file (used for merging)
+ * @param targetFilePath - Full path to where the result should be written
+ * @param relativeTargetPath - Relative path for logging (e.g. "src/routes.tsx")
+ * @param shouldMerge - If true, merges patch with base using route merge strategy
+ */
+export async function applyFile(
+  patchFilePath: string,
+  baseFilePath: string,
+  targetFilePath: string,
+  relativeTargetPath: string,
+  shouldMerge: boolean = false
+): Promise<void> {
+  if (!existsSync(patchFilePath)) {
+    throw new FileOperationError(
+      `Patch file not found: ${patchFilePath}`
+    );
+  }
+
+  // Read the patch content
+  let patchContent = readFileSync(patchFilePath, 'utf-8');
+
+  // Fix __inherit__ import paths for JS/TS files
+  if (isJavaScriptFile(patchFilePath)) {
+    patchContent = fixInheritImportPaths(patchContent);
+  }
+
+  if (shouldMerge) {
+    // Merge strategy - merge patch with base, write to target
+    if (!existsSync(baseFilePath)) {
+      throw new FileOperationError(
+        `Base file not found: ${baseFilePath}. Merge requires base file to exist.`
+      );
+    }
+
+    // Merge patch with base (note: mergeRoutes reads files internally, so we write fixed content to temp)
+    let mergedContent = mergeRoutes(patchFilePath, baseFilePath);
+
+    // Fix imports in merged content
+    if (isJavaScriptFile(targetFilePath)) {
+      mergedContent = fixInheritImportPaths(mergedContent);
+    }
+
+    // Check if target already has this content
+    if (existsSync(targetFilePath)) {
+      const existingContent = readFileSync(targetFilePath, 'utf-8');
+      if (existingContent === mergedContent) {
+        logger.info(`Skipped ${relativeTargetPath} (content unchanged after merge)`);
+        return;
+      }
+    }
+
+    // Ensure target directory exists
+    const targetDirPath = dirname(targetFilePath);
+    if (!existsSync(targetDirPath)) {
+      mkdirSync(targetDirPath, { recursive: true });
+    }
+
+    writeFileSync(targetFilePath, mergedContent, 'utf-8');
+    logger.success(`Merged ${relativeTargetPath}`);
+  } else {
+    // Add/Update strategy - copy patch to target
+    const targetExists = existsSync(targetFilePath);
+
+    if (targetExists) {
+      const existingContent = readFileSync(targetFilePath, 'utf-8');
+      if (existingContent === patchContent) {
+        logger.info(`Skipped ${relativeTargetPath} (content unchanged)`);
+        return;
+      }
+    }
+
+    // Ensure target directory exists
+    const targetDirPath = dirname(targetFilePath);
+    if (!existsSync(targetDirPath)) {
+      mkdirSync(targetDirPath, { recursive: true });
+    }
+
+    // Write the file
+    writeFileSync(targetFilePath, patchContent, 'utf-8');
+
+    if (targetExists) {
+      logger.success(`Updated ${relativeTargetPath}`);
+    } else {
+      logger.success(`Added ${relativeTargetPath}`);
+    }
+  }
+}
+
+/**
+ * Delete a file or directory from the target app
+ *
+ * @param targetFilePath - Full path to the file/directory to delete
+ * @param relativeTargetPath - Relative path for logging (e.g. "src/routes.tsx")
+ */
+export async function deleteFile(
+  targetFilePath: string,
+  relativeTargetPath: string
+): Promise<void> {
+  if (!existsSync(targetFilePath)) {
+    logger.info(`Skipped deleting ${relativeTargetPath} (does not exist)`);
+    return;
+  }
+
+  const stat = statSync(targetFilePath);
+
+  if (stat.isDirectory()) {
+    rmSync(targetFilePath, { recursive: true, force: true });
+    logger.success(`Deleted directory ${relativeTargetPath}`);
+  } else {
+    rmSync(targetFilePath, { force: true });
+    logger.success(`Deleted ${relativeTargetPath}`);
+  }
+}
+
+/**
+ * Prepend content from a feature file to the beginning of a target file
+ *
+ * @param featureFilePath - Full path to the feature file with content to prepend
+ * @param targetFilePath - Full path to the target file to prepend to
+ * @param relativeTargetPath - Relative path for logging (e.g. "src/styles/global.css")
+ */
+export async function prependToFile(
+  featureFilePath: string,
+  targetFilePath: string,
+  relativeTargetPath: string
+): Promise<void> {
+  if (!existsSync(featureFilePath)) {
+    throw new FileOperationError(
+      `Feature file not found: ${featureFilePath}`
+    );
+  }
+
+  if (!existsSync(targetFilePath)) {
+    throw new FileOperationError(
+      `Target file not found: ${targetFilePath}`
+    );
+  }
+
+  // Read both files
+  let featureContent = readFileSync(featureFilePath, 'utf-8');
+  const targetContent = readFileSync(targetFilePath, 'utf-8');
+
+  // Fix __inherit__ imports in feature content if it's a JS/TS file
+  if (isJavaScriptFile(featureFilePath)) {
+    featureContent = fixInheritImportPaths(featureContent);
+  }
+
+  // Prepend feature content to target content
+  const newContent = featureContent + '\n' + targetContent;
+
+  // Check if content would actually change
+  if (targetContent === newContent) {
+    logger.info(`Skipped ${relativeTargetPath} (content unchanged after prepend)`);
+    return;
+  }
+
+  writeFileSync(targetFilePath, newContent, 'utf-8');
+  logger.success(`Prepended to ${relativeTargetPath}`);
+}
+
+/**
+ * Append content from a feature file to the end of a target file
+ *
+ * @param featureFilePath - Full path to the feature file with content to append
+ * @param targetFilePath - Full path to the target file to append to
+ * @param relativeTargetPath - Relative path for logging (e.g. "src/styles/global.css")
+ */
+export async function appendToFile(
+  featureFilePath: string,
+  targetFilePath: string,
+  relativeTargetPath: string
+): Promise<void> {
+  if (!existsSync(featureFilePath)) {
+    throw new FileOperationError(
+      `Feature file not found: ${featureFilePath}`
+    );
+  }
+
+  if (!existsSync(targetFilePath)) {
+    throw new FileOperationError(
+      `Target file not found: ${targetFilePath}`
+    );
+  }
+
+  // Read both files
+  const targetContent = readFileSync(targetFilePath, 'utf-8');
+  let featureContent = readFileSync(featureFilePath, 'utf-8');
+
+  // Fix __inherit__ imports in feature content if it's a JS/TS file
+  if (isJavaScriptFile(featureFilePath)) {
+    featureContent = fixInheritImportPaths(featureContent);
+  }
+
+  // Append feature content to target content
+  const newContent = targetContent + '\n' + featureContent;
+
+  // Check if content would actually change
+  if (targetContent === newContent) {
+    logger.info(`Skipped ${relativeTargetPath} (content unchanged after append)`);
+    return;
+  }
+
+  writeFileSync(targetFilePath, newContent, 'utf-8');
+  logger.success(`Appended to ${relativeTargetPath}`);
+}

package/src/core/package-json-merger.ts

@@ -0,0 +1,129 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { execSync } from 'child_process';
+import type { PackageJsonDependencies } from '../types.js';
+import * as logger from '../utils/logger.js';
+import { getWebApplicationPath } from '../utils/validation.js';
+
+export class PackageJsonMergeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'PackageJsonMergeError';
+  }
+}
+
+/**
+ * Build package specs array from dependencies object
+ * @param dependencies - Object mapping package names to versions
+ * @returns Array of package specs in format "package@version"
+ */
+export function buildPackageSpecs(dependencies: Record<string, string>): string[] {
+  return Object.entries(dependencies).map(([name, version]) => `${name}@${version}`);
+}
+
+/**
+ * Build yarn command for package specs
+ * @param packageSpecs - Array of package specs
+ * @param isDev - Whether these are dev dependencies
+ * @returns yarn command string
+ */
+export function buildInstallCommand(packageSpecs: string[], isDev: boolean): string {
+  const devFlag = isDev ? '--dev ' : '';
+  return `yarn ${devFlag}${packageSpecs.join(' ')}`;
+}
+
+/**
+ * Execute yarn command (extracted for testability)
+ * @param command - yarn command to execute
+ * @param cwd - Working directory
+ */
+export function executeNpmInstall(command: string, cwd: string): void {
+  execSync(command, {
+    cwd,
+    stdio: 'inherit'
+  });
+}
+
+/**
+ * Install dependencies using yarn
+ * @param targetDir - Base directory containing digitalExperiences/webApplications/<app-name>, or direct path to web app directory if webAppDirPath is provided
+ * @param webAppDirPath - Optional direct path to the web application directory
+ */
+export async function mergePackageJson(
+  targetDir: string,
+  patchDependencies: PackageJsonDependencies,
+  webAppDirPath?: string
+): Promise<string[]> {
+  // Get the web application directory where package.json is located
+  const webAppDir = webAppDirPath || getWebApplicationPath(targetDir);
+  const packageJsonPath = join(webAppDir, 'package.json');
+
+  if (!existsSync(packageJsonPath)) {
+    throw new PackageJsonMergeError(
+      `package.json not found at '${packageJsonPath}'. Expected structure: digitalExperiences/webApplications/<app-name>`
+    );
+  }
+
+  try {
+    const changes: string[] = [];
+
+    // Install dependencies
+    if (patchDependencies.dependencies) {
+      const packages = Object.entries(patchDependencies.dependencies);
+
+      if (packages.length > 0) {
+        logger.info(`Installing ${packages.length} dependency/dependencies...`);
+
+        const packageSpecs = buildPackageSpecs(patchDependencies.dependencies);
+        packageSpecs.forEach(spec => logger.info(`  ${spec}`));
+
+        try {
+          const command = buildInstallCommand(packageSpecs, false);
+          executeNpmInstall(command, webAppDir);
+          changes.push(...packageSpecs);
+        } catch (err) {
+          throw new PackageJsonMergeError(
+            `Failed to install dependencies: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+      }
+    }
+
+    // Install devDependencies
+    if (patchDependencies.devDependencies) {
+      const packages = Object.entries(patchDependencies.devDependencies);
+
+      if (packages.length > 0) {
+        logger.info(`Installing ${packages.length} dev dependency/dependencies...`);
+
+        const packageSpecs = buildPackageSpecs(patchDependencies.devDependencies);
+        packageSpecs.forEach(spec => logger.info(`  ${spec}`));
+
+        try {
+          const command = buildInstallCommand(packageSpecs, true);
+          executeNpmInstall(command, webAppDir);
+          changes.push(...packageSpecs.map(spec => `${spec} (dev)`));
+        } catch (err) {
+          throw new PackageJsonMergeError(
+            `Failed to install dev dependencies: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+      }
+    }
+
+    if (changes.length > 0) {
+      logger.success(`Installed ${changes.length} dependency change(s)`);
+    } else {
+      logger.info('No new dependencies to install');
+    }
+
+    return changes;
+  } catch (err) {
+    if (err instanceof PackageJsonMergeError) {
+      throw err;
+    }
+    throw new PackageJsonMergeError(
+      `Failed to install dependencies: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}

package/src/core/patch-loader.ts

@@ -0,0 +1,128 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { pathToFileURL } from 'url';
+import type { Feature, PathMappings } from '../types.js';
+
+export class FeatureLoadError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'FeatureLoadError';
+  }
+}
+
+export type FeatureConfig = {
+  features: Feature[];
+  templateDir: string;
+  webAppName: string;
+  routeFilePath: string;
+  dependencies: string[];
+  pathMappings: PathMappings;
+};
+
+/**
+ * Extract feature name from feature path
+ * Examples:
+ * - 'packages/feature-navigation-menu' -> 'feature-navigation-menu'
+ * - '/absolute/path/to/feature-name' -> 'feature-name'
+ * - 'packages/reference-app-vibe-coding-starter' -> 'reference-app-vibe-coding-starter'
+ */
+function extractFeatureName(featurePath: string): string {
+  const parts = featurePath.split('/');
+  return parts[parts.length - 1];
+}
+
+/**
+ * Load features from a feature's feature.ts file
+ */
+export async function loadFeature(featurePath: string): Promise<FeatureConfig> {
+  const featureFilePath = join(featurePath, 'feature.ts');
+
+  if (!existsSync(featureFilePath)) {
+    throw new FeatureLoadError(
+      `No feature.ts found in feature path '${featurePath}'`
+    );
+  }
+
+  try {
+    // Convert to file URL for dynamic import
+    const featurePathUrl = pathToFileURL(featureFilePath).href;
+    const module = await import(featurePathUrl);
+
+    // Require default export
+    if (!module.default) {
+      throw new FeatureLoadError(
+        `feature.ts must have a default export (array or object) in ${featureFilePath}`
+      );
+    }
+
+    // Helper to check if a value looks like a feature object
+    const isFeatureLike = (value: any): boolean => {
+      return value && typeof value === 'object' && !Array.isArray(value);
+    };
+
+    let features: Feature[];
+
+    if (Array.isArray(module.default)) {
+      features = module.default;
+    } else if (isFeatureLike(module.default)) {
+      features = [module.default];
+    } else {
+      throw new FeatureLoadError(
+        `Default export must be a Feature object or Feature[] array in ${featureFilePath}`
+      );
+    }
+
+    // Extract feature name from path for constructing defaults
+    const featureName = extractFeatureName(featurePath);
+
+    // Extract configuration from features (with defaults)
+    let templateDir = 'template';
+    let webAppName = featureName; // Default to feature name
+    let routeFilePath: string | undefined;
+    let dependencies: string[] = [];
+    let pathMappings: PathMappings = {}; // Default: enabled with no custom mappings
+
+    // Check if any feature specifies custom configuration
+    for (const feature of features) {
+      if (feature.templateDir) {
+        templateDir = feature.templateDir;
+      }
+      if (feature.webAppName) {
+        webAppName = feature.webAppName;
+      }
+      if (feature.routeFilePath) {
+        routeFilePath = feature.routeFilePath;
+      }
+      if (feature.dependencies) {
+        // Merge dependencies from all features
+        dependencies = [...new Set([...dependencies, ...feature.dependencies])];
+      }
+      if (feature.pathMappings) {
+        // If any feature specifies pathMappings, use it
+        // Last one wins if multiple features specify it
+        pathMappings = feature.pathMappings;
+      }
+    }
+
+    // Set default routeFilePath if not explicitly provided
+    if (!routeFilePath) {
+      routeFilePath = `digitalExperiences/webApplications/${webAppName}/src/routes.tsx`;
+    }
+
+    return {
+      features,
+      templateDir,
+      webAppName,
+      routeFilePath,
+      dependencies,
+      pathMappings
+    };
+  } catch (err) {
+    if (err instanceof FeatureLoadError) {
+      throw err;
+    }
+    throw new FeatureLoadError(
+      `Failed to load feature from ${featureFilePath}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { applyPatchesCommand } from './commands/apply-patches.js';
+import { watchPatchesCommand } from './commands/watch-patches.js';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { newAppOrFeatureCommand } from './commands/new-app-feature.js';
+
+// Get package.json for version info
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = join(__dirname, '../package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+
+const program = new Command();
+
+program
+  .name('apply-patches')
+  .description('CLI tool for applying feature patches to base apps')
+  .version(packageJson.version);
+
+program
+  .command('apply-patches')
+  .description('Apply feature patches to an app')
+  .argument('<feature-path>', 'Path to the feature (e.g., packages/feature-navigation-menu)')
+  .argument('<app-path>', 'Path to the app (e.g., packages/base-react-app or my-app)')
+  .argument('<target-dir>', 'Target directory to copy app to before applying patches')
+  .option('--skip-dependency-changes', 'Skip installing dependencies from package.json')
+  .option('--clean', 'Remove target directory if it exists before applying patches')
+  .action(async (featurePath: string, appPath: string, targetDir: string, options: { skipDependencyChanges?: boolean; clean?: boolean }) => {
+    try {
+      await applyPatchesCommand(featurePath, appPath, {
+        targetDirName: targetDir,
+        skipDependencyChanges: options.skipDependencyChanges,
+        clean: options.clean
+      });
+      process.exit(0);
+    } catch (err) {
+      process.exit(1);
+    }
+  });
+
+program
+  .command('watch-patches')
+  .description('Watch feature template directory and auto-apply patches on changes')
+  .argument('<feature-path>', 'Path to the feature (e.g., packages/feature-navigation-menu)')
+  .argument('<app-path>', 'Path to the app (e.g., packages/base-react-app or my-app)')
+  .argument('<target-dir>', 'Target directory to apply patches to')
+  .option('--clean', 'Remove target directory if it exists before applying patches')
+  .action(async (featurePath: string, appPath: string, targetDir: string, options: { clean?: boolean }) => {
+    try {
+      await watchPatchesCommand(featurePath, appPath, targetDir, options);
+    } catch (err) {
+      process.exit(1);
+    }
+  });
+
+program
+  .command('new-feature')
+  .description('Create a new feature package from the base-feature template')
+  .argument('<feature-name>', 'Name of the feature (will be prefixed with "feature-")')
+  .action(async (featureName: string) => {
+    try {
+      await newAppOrFeatureCommand(featureName, 'feature');
+      process.exit(0);
+    } catch (err) {
+      process.exit(1);
+    }
+  });
+
+program
+  .command('new-app')
+  .description('Create a new reference app package from the base-reference-app template')
+  .argument('<app-name>', 'Name of the app (will be prefixed with "app-")')
+  .action(async (appName: string) => {
+    try {
+      await newAppOrFeatureCommand(appName, 'app');
+      process.exit(0);
+    } catch (err) {
+      process.exit(1);
+    }
+  });
+
+// If no command specified, default to apply-patches
+if (process.argv.length > 2 && !process.argv[2].startsWith('-')) {
+  // If first argument is not a recognized command, treat as apply-patches command
+  const args = process.argv.slice(2);
+  const knownCommands = ['apply-patches', 'watch-patches', 'new-feature', 'new-app'];
+  if (!knownCommands.includes(args[0]) && !args[0].startsWith('-')) {
+    process.argv.splice(2, 0, 'apply-patches');
+  }
+}
+
+program.parse(process.argv);

package/src/types.ts

@@ -0,0 +1,23 @@
+export type PackageJsonDependencies = {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+}
+
+export type PathMapping = {
+    from: string; // Template path prefix (e.g., "webApp")
+    to: string; // Target path prefix (e.g., "digitalExperiences/webApplications/<feature-name>")
+};
+
+export type PathMappings = {
+    mappings?: PathMapping[]; // Array of custom path mappings
+    enabled?: boolean; // Enable/disable all mappings (default: true)
+};
+
+export type Feature = {
+    templateDir?: string; // The directory in the feature where the template files are located, defaults to 'template'
+    webAppName?: string; // The name of the web application, defaults to feature name
+    routeFilePath?: string; // The route file to merge (relative path from template dir), defaults to 'digitalExperiences/webApplications/<webAppName>/src/routes.tsx'
+    packageJson?: PackageJsonDependencies;
+    dependencies?: string[]; // Array of feature paths that this feature depends on (e.g., ['packages/feature-navigation-menu'])
+    pathMappings?: PathMappings; // Path mapping configuration for simplified directory structures (enabled by default)
+}

package/src/utils/debounce.ts

@@ -0,0 +1,23 @@
+/**
+ * Creates a debounced function that delays invoking func until after wait milliseconds
+ * have elapsed since the last time the debounced function was invoked.
+ */
+export function debounce<T extends (...args: any[]) => any>(
+  func: T,
+  wait: number
+): (...args: Parameters<T>) => void {
+  let timeoutId: NodeJS.Timeout | null = null;
+
+  return function debounced(...args: Parameters<T>): void {
+    // Clear any existing timeout
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+    }
+
+    // Set a new timeout
+    timeoutId = setTimeout(() => {
+      func(...args);
+      timeoutId = null;
+    }, wait);
+  };
+}