@sfdc-webapps/cli 1.0.2

package/src/commands/new-app-feature.ts

@@ -0,0 +1,203 @@
+import { join } from 'path';
+import * as logger from '../utils/logger.js';
+import { getMonorepoRoot } from '../utils/paths.js';
+import { cpSync, existsSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'fs';
+import { validateAppOrFeatureName, ValidationError } from '../utils/validation.js';
+
+/**
+ * Create a new app or feature from the base-reference-app or base-feature template
+ *
+ * @param appOrFeatureName - Name of the app or feature (without "app-" or "feature-" prefix)
+ */
+export async function newAppOrFeatureCommand(appOrFeatureName: string, appOrFeatureType: 'app' | 'feature'): Promise<void> {
+    let targetDir: string | undefined;
+
+    try {
+        logger.heading(`Creating new ${appOrFeatureType}: ${appOrFeatureName}`);
+
+        // Step 1: Validate feature name format
+        logger.info(`Validating ${appOrFeatureType} name...`);
+        validateAppOrFeatureName(appOrFeatureName);
+
+        // Step 2: Generate full feature name with prefix
+        const fullFeatureName = appOrFeatureName.startsWith(`${appOrFeatureType}-`)
+            ? appOrFeatureName
+            : `${appOrFeatureType}-${appOrFeatureName}`;
+        const rawName = fullFeatureName.replace(/^${appOrFeatureType}-/, '');
+
+        logger.success(`${appOrFeatureType} name validated: ${fullFeatureName}`);
+
+        // Step 3: Check if feature already exists
+        logger.info(`Checking if ${appOrFeatureType} already exists...`);
+        if (checkAppFeatureExists(fullFeatureName)) {
+            throw new ValidationError(
+                `${appOrFeatureType} '${fullFeatureName}' already exists at packages/${fullFeatureName}.\nPlease choose a different name or remove the existing ${appOrFeatureType}.`
+            );
+        }
+        logger.success('Feature name available');
+
+        // Step 4: Validate base feature template
+        logger.info('Validating base feature template...');
+        const baseAppOrFeaturePath = validateBaseAppOrFeature(appOrFeatureType);
+        logger.success('Base feature template validated');
+
+        // Step 5: Create target directory and copy
+        const monorepoRoot = getMonorepoRoot();
+        targetDir = join(monorepoRoot, 'packages', fullFeatureName);
+
+        logger.info(`Copying base feature template to packages/${fullFeatureName}...`);
+        cpSync(baseAppOrFeaturePath, targetDir, { recursive: true });
+        logger.success('Template copied');
+
+        // Step 6: Rename webApplications directory
+        logger.info('Renaming template directories...');
+        const templateName = appOrFeatureType === 'app' ? 'reference-app' : 'feature';
+        const oldWebAppPath = join(targetDir, `template/digitalExperiences/webApplications/base-${templateName}`);
+        const newWebAppPath = join(targetDir, 'template/digitalExperiences/webApplications', rawName);
+
+        if (existsSync(oldWebAppPath)) {
+            renameSync(oldWebAppPath, newWebAppPath);
+            logger.success(`Renamed: base-${templateName} → ${rawName}`);
+        }
+
+        // Step 7: Update package.json
+        logger.info('Updating package.json...');
+        const packageJsonPath = join(targetDir, 'package.json');
+        const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+
+        packageJson.name = fullFeatureName;
+
+        // Update scripts to reference new feature name
+        // Replace both "base-feature" and any existing "feature-*" patterns
+        const regexPattern = new RegExp(`base-${templateName}`, 'g');
+        if (packageJson.scripts) {
+            if (packageJson.scripts.dev) {
+                packageJson.scripts.dev = packageJson.scripts.dev
+                    .replace(regexPattern, fullFeatureName);
+            }
+            if (packageJson.scripts['test-patch']) {
+                packageJson.scripts['test-patch'] = packageJson.scripts['test-patch']
+                    .replace(regexPattern, fullFeatureName);
+            }
+            if (packageJson.scripts.watch) {
+                packageJson.scripts.watch = packageJson.scripts.watch
+                    .replace(regexPattern, fullFeatureName);
+            }
+        }
+
+        writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
+        logger.success('package.json updated');
+
+        // Step 8: Update tsconfig.app.json
+        logger.info('Updating tsconfig.app.json...');
+        const tsconfigAppPath = join(targetDir, 'tsconfig.app.json');
+        let tsconfigContent = readFileSync(tsconfigAppPath, 'utf-8');
+
+        // Replace the include path (handles both single and array format)
+        // tsconfigContent = tsconfigContent.replace(
+        //   /"include":\s*\[.*?\]/s,
+        //   `"include": ["template/digitalExperiences/webApplications/${rawName}"]`
+        // );
+
+        writeFileSync(tsconfigAppPath, tsconfigContent);
+        logger.success('tsconfig.app.json updated');
+
+        // Step 9: Success message
+        logger.heading('\n✓ Success');
+        logger.success(`Created feature: packages/${fullFeatureName}`);
+        logger.info('\nNext steps:');
+        logger.info(`  1. cd packages/${fullFeatureName}`);
+        logger.info('  2. Customize template files in template/ directory');
+        logger.info(`  3. Update feature.ts with ${appOrFeatureType} configuration`);
+        logger.info(`  4. Test with: yarn apply-patches packages/${fullFeatureName} packages/base-react-app test-app`);
+
+    } catch (err) {
+        // Cleanup on failure
+        if (targetDir && existsSync(targetDir)) {
+            logger.info(`\nCleaning up partially created ${appOrFeatureType}...`);
+            rmSync(targetDir, { recursive: true, force: true });
+            logger.info('Cleanup complete');
+        }
+
+        // Handle different error types
+        if (err instanceof Error) {
+            // Handle permission errors
+            if (err.message.includes('EACCES')) {
+                logger.error(`\n✗ Permission denied. You do not have permission to create ${appOrFeatureType}s in the packages directory.`);
+                logger.info('Try running with appropriate permissions or check directory ownership.');
+                throw new ValidationError('Permission denied');
+            }
+
+            // Handle disk space errors
+            if (err.message.includes('ENOSPC')) {
+                logger.error(`\n✗ Not enough disk space to create ${appOrFeatureType}.`);
+                logger.info('Free up some disk space and try again.');
+                throw new ValidationError('Insufficient disk space');
+            }
+        }
+
+        // Log error if not already logged
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        const skipLogging = err instanceof ValidationError;
+
+        if (!skipLogging) {
+            logger.error(`\n✗ Failed to create ${appOrFeatureType}: ${errorMessage}`);
+        } else {
+            logger.error(`\n✗ ${errorMessage}`);
+        }
+
+        throw err;
+    }
+}
+
+/**
+ * Check if a feature already exists in the packages directory
+ */
+function checkAppFeatureExists(appOrFeatureName: string): boolean {
+    const monorepoRoot = getMonorepoRoot();
+    const appOrFeaturePath = join(monorepoRoot, 'packages', appOrFeatureName);
+    return existsSync(appOrFeaturePath);
+}
+
+/**
+ * Validate that the base-feature and base-reference-app template exists and is valid
+ * Returns the absolute path to the base-feature or base-reference-app directory
+ */
+function validateBaseAppOrFeature(appOrFeatureType: 'app' | 'feature'): string {
+    const monorepoRoot = getMonorepoRoot();
+    const templateName = appOrFeatureType === 'app' ? 'reference-app' : 'feature';
+    const baseAppOrFeaturePath = join(monorepoRoot, `packages/base-${templateName}`);
+  
+    if (!existsSync(baseAppOrFeaturePath)) {
+      throw new ValidationError(
+        `Base ${templateName} template not found at packages/base-${templateName}.\nCannot create new ${appOrFeatureType}.`
+      );
+    }
+  
+    if (!statSync(baseAppOrFeaturePath).isDirectory()) {
+      throw new ValidationError(
+        `Base ${templateName} template at packages/base-${templateName} is not a directory.`
+      );
+    }
+  
+    // Check critical files exist
+    const requiredFiles = [
+      'package.json',
+      'feature.ts',
+      'tsconfig.app.json',
+      'tsconfig.json',
+      'tsconfig.node.json',
+      'template'
+    ];
+  
+    for (const file of requiredFiles) {
+      const filePath = join(baseAppOrFeaturePath, file);
+      if (!existsSync(filePath)) {
+        throw new ValidationError(
+          `Base ${appOrFeatureType} template is incomplete.\nMissing required file: ${file}`
+        );
+      }
+    }
+  
+    return baseAppOrFeaturePath;
+  }

package/src/commands/watch-patches.ts

@@ -0,0 +1,173 @@
+import { watch, type ChangeEvent } from 'turbowatch';
+import { join, relative, basename } from 'path';
+import { existsSync, cpSync, rmSync } from 'fs';
+import { applyPatchesCommand } from './apply-patches.js';
+import { validateAndResolveFeaturePath, validateAndResolveAppPath } from '../utils/validation.js';
+import { getMonorepoRoot, translatePathToBaseApp } from '../utils/paths.js';
+import { loadFeature } from '../core/patch-loader.js';
+import * as logger from '../utils/logger.js';
+
+export async function watchPatchesCommand(
+  featurePath: string,
+  appPath: string,
+  targetDirName: string,
+  options: { clean?: boolean } = {}
+): Promise<{ shutdown: () => Promise<void> }> {
+  try {
+    logger.heading(`Starting watch mode for ${featurePath}...`);
+
+    // Step 1: Validate inputs
+    logger.info('Validating feature and app path...');
+    const featureDir = validateAndResolveFeaturePath(featurePath);
+    validateAndResolveAppPath(appPath);
+    logger.success('Validation passed');
+
+    // Step 2: Apply feature initially (with dependencies)
+    logger.info('Applying feature initially...');
+    await applyPatchesCommand(featurePath, appPath, {
+      targetDirName: targetDirName,
+      skipDependencyChanges: false,
+      clean: options.clean
+    });
+    logger.success('Initial feature applied successfully\n');
+
+    // Step 3: Load feature config to get template directory
+    const { templateDir } = await loadFeature(featureDir);
+    const watchPath = join(featureDir, templateDir);
+
+    // Resolve base app and target directory paths
+    const baseAppPath = validateAndResolveAppPath(appPath);
+    const monorepoRoot = getMonorepoRoot();
+    const targetDir = targetDirName ? join(monorepoRoot, targetDirName) : baseAppPath;
+
+    logger.info(`👁  Watching ${watchPath} for changes...`);
+    logger.info('   Press Ctrl+C to stop watching\n');
+
+    // Create feature application function
+    const applyPatches = async (changedPath: string) => {
+      try {
+        const relativePath = changedPath.replace(watchPath + '/', '');
+        logger.info(`📝 Change detected in ${relativePath}`);
+        logger.info('⟳  Re-applying feature...\n');
+
+        const startTime = Date.now();
+        await applyPatchesCommand(featurePath, appPath, {
+          targetDirName: targetDirName,
+          skipDependencyChanges: true,
+          clean: options.clean
+        });
+        const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+
+        logger.success(`\n✓ Feature re-applied successfully (${elapsed}s)`);
+        logger.info('👁  Watching for changes...\n');
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        // Only log if not already handled
+        const skipLogging = [
+          'Path conflict - cannot proceed',
+          'Delete validation failed - cannot proceed',
+          'Inherit validation failed - cannot proceed',
+          'Prepend validation failed - cannot proceed',
+          'Append validation failed - cannot proceed',
+          'Route deletion failed - cannot proceed'
+        ].includes(errorMessage);
+
+        if (!skipLogging) {
+          logger.error(`\n✗ Failed to apply feature: ${errorMessage}`);
+        }
+        logger.info('   Fix the issue and save again to retry');
+        logger.info('👁  Watching for changes...\n');
+      }
+    };
+
+    // Handle file deletion - restore base app file if it exists, otherwise delete
+    const handleDeletion = async (deletedPath: string) => {
+      try {
+        const relativePath = deletedPath.replace(watchPath + '/', '');
+        logger.info(`🗑  Deletion detected in ${relativePath}`);
+
+        // Calculate paths
+        const relativeFromFeature = relative(watchPath, deletedPath);
+        const featureName = basename(featurePath);
+
+        // Translate the path to the base app structure
+        const translatedPath = translatePathToBaseApp(relativeFromFeature, featureName, baseAppPath);
+        const targetFilePath = join(targetDir, translatedPath);
+        const baseFilePath = join(baseAppPath, translatedPath);
+
+        // Check if file exists in base app
+        if (existsSync(baseFilePath)) {
+          // Restore base app version
+          cpSync(baseFilePath, targetFilePath);
+          logger.success(`✓ Restored base app version of ${translatedPath}`);
+        } else {
+          // No base version, delete from target
+          if (existsSync(targetFilePath)) {
+            rmSync(targetFilePath);
+            logger.success(`✓ Deleted ${translatedPath}`);
+          }
+        }
+
+        logger.info('👁  Watching for changes...\n');
+      } catch (err) {
+        logger.error(`\n✗ Failed to handle deletion: ${err instanceof Error ? err.message : String(err)}`);
+        logger.info('   Will retry on next file change');
+        logger.info('👁  Watching for changes...\n');
+      }
+    };
+
+    // Set up turbowatch watcher
+    const controller = await watch({
+      project: watchPath,
+      debounce: {
+        wait: 500
+      },
+      triggers: [
+        {
+          expression: ['anyof', ['match', '*.tsx', 'basename'], ['match', '*.ts', 'basename'], ['match', '*.css', 'basename']],
+          name: 'source-files',
+          onChange: async ({ files }: ChangeEvent) => {
+            for (const file of files) {
+              // Check if file still exists to detect deletions
+              if (!existsSync(file.name)) {
+                await handleDeletion(file.name);
+              }
+              await applyPatches(file.name);
+            }
+          }
+        }
+      ]
+    });
+
+    // Handle graceful shutdown
+    const cleanup = async () => {
+      logger.info('\n🛑 Stopping watcher...');
+      await controller.shutdown();
+      logger.success('✓ Watch mode stopped');
+      process.exit(0);
+    };
+
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+
+    // Return controller for tests to use
+    return controller;
+
+  } catch (err) {
+    // Only log error if it's not already been logged
+    const errorMessage = err instanceof Error ? err.message : String(err);
+    const skipLogging = [
+      'Path conflict - cannot proceed',
+      'Delete validation failed - cannot proceed',
+      'Inherit validation failed - cannot proceed',
+      'Prepend validation failed - cannot proceed',
+      'Append validation failed - cannot proceed',
+      'Route deletion failed - cannot proceed'
+    ].includes(errorMessage);
+
+    if (!skipLogging) {
+      logger.error(`\nWatch mode failed: ${errorMessage}`);
+    }
+    throw err;
+  }
+}

package/src/core/dependency-resolver.ts

@@ -0,0 +1,175 @@
+import { join, isAbsolute } from 'path';
+import { validateAndResolveFeaturePath } from '../utils/validation.js';
+import { loadFeature, type FeatureConfig } from './patch-loader.js';
+import { getMonorepoRoot } from '../utils/paths.js';
+
+/**
+ * Represents a resolved feature with its configuration
+ */
+export type ResolvedFeature = {
+  featurePath: string;      // Original path (may be relative)
+  featureDir: string;        // Absolute validated directory
+  config: FeatureConfig;     // Loaded feature configuration
+};
+
+/**
+ * Result of dependency resolution
+ */
+export type DependencyResolutionResult = {
+  orderedFeatures: ResolvedFeature[];      // Features in application order (deps first)
+  dependencyGraph: Map<string, string[]>;  // For debugging/visualization
+};
+
+/**
+ * Base error for dependency resolution failures
+ */
+export class DependencyResolutionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'DependencyResolutionError';
+  }
+}
+
+/**
+ * Error thrown when a circular dependency is detected
+ */
+export class CircularDependencyError extends DependencyResolutionError {
+  constructor(public cycle: string[]) {
+    const cycleStr = cycle.join(' → ');
+    super(`Circular dependency detected:\n  ${cycleStr}\n\nPlease remove one of these dependencies to break the cycle.`);
+    this.name = 'CircularDependencyError';
+  }
+}
+
+/**
+ * Normalize a feature path to an absolute path for consistent comparison
+ *
+ * @param featurePath - Relative or absolute feature path
+ * @returns Absolute path to the feature
+ */
+function normalizePath(featurePath: string): string {
+  // If already absolute, return as-is
+  if (isAbsolute(featurePath)) {
+    return featurePath;
+  }
+
+  // If relative, resolve from monorepo root
+  return join(getMonorepoRoot(), featurePath);
+}
+
+/**
+ * Recursively resolve dependencies using depth-first search with post-order traversal
+ *
+ * @param featurePath - Path to the feature to resolve
+ * @param visited - Set of features currently being processed (for cycle detection)
+ * @param resolved - Set of features that have been fully processed
+ * @param result - Accumulator for ordered features
+ * @param dependencyGraph - Map of feature paths to their dependencies
+ * @param dependencyChain - Current chain of dependencies (for error messages)
+ */
+async function resolveDependenciesRecursive(
+  featurePath: string,
+  visited: Set<string>,
+  resolved: Set<string>,
+  result: ResolvedFeature[],
+  dependencyGraph: Map<string, string[]>,
+  dependencyChain: string[]
+): Promise<void> {
+  const normalizedPath = normalizePath(featurePath);
+
+  // Skip if already resolved (handles diamond dependencies)
+  if (resolved.has(normalizedPath)) {
+    return;
+  }
+
+  // Circular dependency detection
+  if (visited.has(normalizedPath)) {
+    const cycle = [...dependencyChain, featurePath];
+    throw new CircularDependencyError(cycle);
+  }
+
+  // Mark as visiting
+  visited.add(normalizedPath);
+  dependencyChain.push(featurePath);
+
+  try {
+    // Validate and load feature
+    const featureDir = validateAndResolveFeaturePath(featurePath);
+    const config = await loadFeature(featureDir);
+
+    // Store in dependency graph for debugging
+    dependencyGraph.set(normalizedPath, config.dependencies);
+
+    // Recursively resolve dependencies (depth-first)
+    for (const depPath of config.dependencies) {
+      await resolveDependenciesRecursive(
+        depPath,
+        visited,
+        resolved,
+        result,
+        dependencyGraph,
+        [...dependencyChain] // Pass copy for independent error messages
+      );
+    }
+
+    // Post-order: add after all dependencies are resolved
+    result.push({
+      featurePath,
+      featureDir,
+      config
+    });
+
+    // Mark as resolved
+    resolved.add(normalizedPath);
+  } finally {
+    // Clean up visiting state
+    visited.delete(normalizedPath);
+    dependencyChain.pop();
+  }
+}
+
+/**
+ * Resolve all dependencies for a feature recursively
+ * Returns features in dependency order (dependencies first, main feature last)
+ *
+ * @param featurePath - Path to the main feature
+ * @returns Resolution result with ordered features and dependency graph
+ * @throws CircularDependencyError if circular dependencies are detected
+ * @throws DependencyResolutionError if a dependency cannot be loaded
+ */
+export async function resolveDependencies(
+  featurePath: string
+): Promise<DependencyResolutionResult> {
+  const visited = new Set<string>();
+  const resolved = new Set<string>();
+  const result: ResolvedFeature[] = [];
+  const dependencyGraph = new Map<string, string[]>();
+  const dependencyChain: string[] = [];
+
+  try {
+    await resolveDependenciesRecursive(
+      featurePath,
+      visited,
+      resolved,
+      result,
+      dependencyGraph,
+      dependencyChain
+    );
+
+    return {
+      orderedFeatures: result,
+      dependencyGraph
+    };
+  } catch (err) {
+    // Re-throw our custom errors as-is
+    if (err instanceof DependencyResolutionError) {
+      throw err;
+    }
+
+    // Wrap other errors
+    const message = err instanceof Error ? err.message : String(err);
+    throw new DependencyResolutionError(
+      `Failed to resolve dependencies: ${message}`
+    );
+  }
+}