@sfdc-webapps/cli 1.0.2

package/test/e2e/watch-patches.spec.ts

@@ -0,0 +1,237 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { join } from 'path';
+import { existsSync, writeFileSync, unlinkSync, readFileSync, mkdirSync } from 'fs';
+import { createTempDir, cleanupTempDir } from '../helpers/create-temp-dir.js';
+import { copyFixture, getFixturePath } from '../helpers/fixtures.js';
+import { spawnWatchPatches } from '../helpers/cli-runner.js';
+import type { ChildProcess } from 'child_process';
+
+describe('watch-patches E2E', () => {
+  let tempDir: string;
+  let watchProcess: ChildProcess | null = null;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(async () => {
+    // Cleanup watcher if still running
+    if (watchProcess) {
+      watchProcess.kill('SIGTERM');
+      // Wait for process to exit
+      await new Promise(resolve => setTimeout(resolve, 100));
+      watchProcess = null;
+    }
+    cleanupTempDir(tempDir);
+  });
+
+  describe('Basic watch functionality', () => {
+    it('should detect and re-apply changes to feature files', async () => {
+      // Setup: Copy base app and watch fixture to temp location
+      const baseAppDir = copyFixture('base-app', join(tempDir, 'base-app'));
+      const targetDir = join(tempDir, 'watch-basic-target');
+
+      // Copy watch-basic fixture to a modifiable temp location
+      const featureDir = join(tempDir, 'watch-basic-feature');
+      copyFixture('watch/watch-basic', featureDir);
+
+      // Start watch mode via CLI
+      const watcher = spawnWatchPatches(featureDir, baseAppDir, targetDir, { clean: false });
+      watchProcess = watcher.process;
+
+      // Wait for initial application (longer timeout for spawned process)
+      await new Promise(resolve => setTimeout(resolve, 1500));
+
+      // Verify initial application
+      const targetFile = join(targetDir, 'digitalExperiences/webApplications/watch-basic/src/placeholder.tsx');
+      expect(existsSync(targetFile)).toBe(true);
+      const initialContent = readFileSync(targetFile, 'utf-8');
+
+      // Modify a file in the feature directory
+      const featureFile = join(featureDir, 'template/digitalExperiences/webApplications/watch-basic/src/placeholder.tsx');
+      const newContent = '// Modified content\nexport default function Placeholder() { return <div>Modified!</div>; }';
+      writeFileSync(featureFile, newContent);
+
+      // Wait for watch to detect and re-apply (debounce is 500ms)
+      await new Promise(resolve => setTimeout(resolve, 1000));
+
+      // Verify the change was applied
+      const updatedContent = readFileSync(targetFile, 'utf-8');
+      expect(updatedContent).toContain('Modified!');
+      expect(updatedContent).not.toBe(initialContent);
+
+      // Stop watch mode
+      if (watchProcess) {
+        watchProcess.kill('SIGTERM');
+        await new Promise(resolve => setTimeout(resolve, 100));
+        watchProcess = null;
+      }
+    }, 10000);
+  });
+
+  describe('Debounce functionality', () => {
+    it('should debounce rapid file changes', async () => {
+      // Setup
+      const baseAppDir = copyFixture('base-app', join(tempDir, 'base-app'));
+      const targetDir = join(tempDir, 'watch-debounce-target');
+      const featureDir = join(tempDir, 'watch-debounce-feature');
+      copyFixture('watch/watch-debounce', featureDir);
+
+      // Start watch mode via CLI
+      const watcher = spawnWatchPatches(featureDir, baseAppDir, targetDir, { clean: false });
+      watchProcess = watcher.process;
+
+      // Wait for initial application (longer timeout for spawned process)
+      await new Promise(resolve => setTimeout(resolve, 1500));
+
+      const featureFile = join(featureDir, 'template/digitalExperiences/webApplications/watch-debounce/src/placeholder.tsx');
+      const targetFile = join(targetDir, 'digitalExperiences/webApplications/watch-debounce/src/placeholder.tsx');
+
+      // Track how many times the file changed
+      let changeCount = 0;
+      const originalContent = readFileSync(targetFile, 'utf-8');
+
+      // Make rapid changes (3 changes within 200ms)
+      writeFileSync(featureFile, '// Change 1');
+      await new Promise(resolve => setTimeout(resolve, 50));
+      writeFileSync(featureFile, '// Change 2');
+      await new Promise(resolve => setTimeout(resolve, 50));
+      writeFileSync(featureFile, '// Change 3 - Final');
+
+      // Wait for debounce + apply (debounce is 500ms, so total ~800ms should be enough)
+      await new Promise(resolve => setTimeout(resolve, 1000));
+
+      // Verify only the final change was applied (debounced)
+      const finalContent = readFileSync(targetFile, 'utf-8');
+      expect(finalContent).toContain('Change 3 - Final');
+      expect(finalContent).not.toContain('Change 1');
+      expect(finalContent).not.toContain('Change 2');
+
+      // Stop watch mode
+      if (watchProcess) {
+        watchProcess.kill('SIGTERM');
+        await new Promise(resolve => setTimeout(resolve, 100));
+        watchProcess = null;
+      }
+    }, 10000);
+  });
+
+  describe('Multiple files', () => {
+    it('should detect changes across multiple files', async () => {
+      // Setup
+      const baseAppDir = copyFixture('base-app', join(tempDir, 'base-app'));
+      const targetDir = join(tempDir, 'watch-multiple-target');
+      const featureDir = join(tempDir, 'watch-multiple-feature');
+      copyFixture('watch/watch-multiple-files', featureDir);
+
+      // Start watch mode via CLI
+      const watcher = spawnWatchPatches(featureDir, baseAppDir, targetDir, { clean: false });
+      watchProcess = watcher.process;
+
+      // Wait for initial application (longer timeout for spawned process)
+      await new Promise(resolve => setTimeout(resolve, 1500));
+
+      // Modify multiple files
+      const componentsDir = join(featureDir, 'template/digitalExperiences/webApplications/watch-multiple-files/src/components');
+      const stylesDir = join(featureDir, 'template/digitalExperiences/webApplications/watch-multiple-files/src/styles');
+
+      if (!existsSync(componentsDir)) mkdirSync(componentsDir, { recursive: true });
+      if (!existsSync(stylesDir)) mkdirSync(stylesDir, { recursive: true });
+
+      writeFileSync(join(componentsDir, 'Header.tsx'), '// Header component');
+      await new Promise(resolve => setTimeout(resolve, 100));
+      writeFileSync(join(stylesDir, 'theme.css'), '/* Theme styles */');
+
+      // Wait for changes to be applied
+      await new Promise(resolve => setTimeout(resolve, 1000));
+
+      // Verify both files were applied
+      expect(existsSync(join(targetDir, 'digitalExperiences/webApplications/watch-multiple-files/src/components/Header.tsx'))).toBe(true);
+      expect(existsSync(join(targetDir, 'digitalExperiences/webApplications/watch-multiple-files/src/styles/theme.css'))).toBe(true);
+
+      // Stop watch mode
+      if (watchProcess) {
+        watchProcess.kill('SIGTERM');
+        await new Promise(resolve => setTimeout(resolve, 100));
+        watchProcess = null;
+      }
+    }, 10000);
+  });
+
+  describe('File additions and deletions', () => {
+    it('should handle file additions during watch', async () => {
+      // Setup
+      const baseAppDir = copyFixture('base-app', join(tempDir, 'base-app'));
+      const targetDir = join(tempDir, 'watch-add-delete-target');
+      const featureDir = join(tempDir, 'watch-add-delete-feature');
+      copyFixture('watch/watch-add-delete-files', featureDir);
+
+      // Start watch mode via CLI
+      const watcher = spawnWatchPatches(featureDir, baseAppDir, targetDir, { clean: false });
+      watchProcess = watcher.process;
+
+      // Wait for initial application (longer timeout for spawned process)
+      await new Promise(resolve => setTimeout(resolve, 1500));
+
+      // Add a new file to the feature
+      const srcDir = join(featureDir, 'template/digitalExperiences/webApplications/watch-add-delete-files/src');
+      const newFile = join(srcDir, 'NewComponent.tsx');
+      writeFileSync(newFile, '// New component added during watch');
+
+      // Wait for detection and application
+      await new Promise(resolve => setTimeout(resolve, 1000));
+
+      // Verify new file was applied
+      const targetNewFile = join(targetDir, 'digitalExperiences/webApplications/watch-add-delete-files/src/NewComponent.tsx');
+      expect(existsSync(targetNewFile)).toBe(true);
+      expect(readFileSync(targetNewFile, 'utf-8')).toContain('New component added during watch');
+
+      // Stop watch mode
+      if (watchProcess) {
+        watchProcess.kill('SIGTERM');
+        await new Promise(resolve => setTimeout(resolve, 100));
+        watchProcess = null;
+      }
+    }, 10000);
+
+    it('should handle file deletions during watch', async () => {
+      // Setup
+      const baseAppDir = copyFixture('base-app', join(tempDir, 'base-app'));
+      const targetDir = join(tempDir, 'watch-delete-target');
+      const featureDir = join(tempDir, 'watch-delete-feature');
+      copyFixture('watch/watch-add-delete-files', featureDir);
+
+      // Start watch mode with clean: true to properly handle deletions via CLI
+      const watcher = spawnWatchPatches(featureDir, baseAppDir, targetDir, { clean: true });
+      watchProcess = watcher.process;
+
+      // Wait for initial application (longer timeout for spawned process)
+      await new Promise(resolve => setTimeout(resolve, 1500));
+
+      // Verify initial file exists
+      const initialFile = join(featureDir, 'template/digitalExperiences/webApplications/watch-add-delete-files/src/initial.tsx');
+      const targetInitialFile = join(targetDir, 'digitalExperiences/webApplications/watch-add-delete-files/src/initial.tsx');
+      expect(existsSync(targetInitialFile)).toBe(true);
+
+      // Delete a file from the feature
+      if (existsSync(initialFile)) {
+        unlinkSync(initialFile);
+      }
+
+      // Wait for detection and handling
+      await new Promise(resolve => setTimeout(resolve, 1000));
+
+      // After deletion, the file should be restored from base app or removed
+      // (depending on whether it exists in base app)
+      // For this test, since it's a feature-specific file, it should be removed
+      expect(existsSync(targetInitialFile)).toBe(false);
+
+      // Stop watch mode
+      if (watchProcess) {
+        watchProcess.kill('SIGTERM');
+        await new Promise(resolve => setTimeout(resolve, 100));
+        watchProcess = null;
+      }
+    }, 10000);
+  });
+});

package/test/helpers/cli-runner.ts

@@ -0,0 +1,100 @@
+import { spawn } from 'child_process';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CLI_PATH = join(__dirname, '../../src/index.ts');
+
+export interface CliResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * Runs the CLI command via tsx (for TypeScript execution without build step)
+ */
+export async function runCli(args: string[]): Promise<CliResult> {
+  return new Promise((resolve) => {
+    const child = spawn('tsx', [CLI_PATH, ...args], {
+      env: { ...process.env, FORCE_COLOR: '0' } // Disable colors for easier parsing
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout?.on('data', (data) => {
+      stdout += data.toString();
+    });
+
+    child.stderr?.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    child.on('close', (code) => {
+      resolve({
+        exitCode: code ?? 1,
+        stdout,
+        stderr
+      });
+    });
+
+    child.on('error', (err) => {
+      resolve({
+        exitCode: 1,
+        stdout,
+        stderr: stderr + err.message
+      });
+    });
+  });
+}
+
+/**
+ * Runs apply-patches command via CLI
+ */
+export async function runApplyPatches(
+  featurePath: string,
+  appPath: string,
+  targetDir: string,
+  options: { skipDependencyChanges?: boolean; clean?: boolean } = {}
+): Promise<CliResult> {
+  const args = ['apply-patches', featurePath, appPath, targetDir];
+
+  if (options.skipDependencyChanges) {
+    args.push('--skip-dependency-changes');
+  }
+
+  if (options.clean) {
+    args.push('--clean');
+  }
+
+  return runCli(args);
+}
+
+/**
+ * Runs watch-patches command via CLI
+ * Note: For watch mode, caller must handle terminating the process
+ */
+export function spawnWatchPatches(
+  featurePath: string,
+  appPath: string,
+  targetDir: string,
+  options: { clean?: boolean } = {}
+): { process: ReturnType<typeof spawn>; kill: () => void } {
+  const args = ['watch-patches', featurePath, appPath, targetDir];
+
+  if (options.clean) {
+    args.push('--clean');
+  }
+
+  const child = spawn('tsx', [CLI_PATH, ...args], {
+    env: { ...process.env, FORCE_COLOR: '0' }
+  });
+
+  return {
+    process: child,
+    kill: () => {
+      child.kill('SIGTERM');
+    }
+  };
+}

package/test/helpers/compare-directories.ts

@@ -0,0 +1,197 @@
+import { readdirSync, statSync, readFileSync, existsSync, cpSync, mkdirSync, rmSync } from 'fs';
+import { join, relative } from 'path';
+
+export interface FileDifference {
+  type: 'missing' | 'extra' | 'content' | 'type-mismatch';
+  path: string;
+  details?: string;
+}
+
+/**
+ * Normalize whitespace and line endings for comparison
+ */
+function normalizeContent(content: string): string {
+  return content
+    .replace(/\r\n/g, '\n') // Normalize line endings
+    .trim(); // Remove trailing whitespace
+}
+
+/**
+ * Check if a path should be ignored in comparisons
+ */
+function shouldIgnore(path: string): boolean {
+  const ignoredNames = [
+    'node_modules',
+    'dist',
+    '.git',
+    '.DS_Store',
+    'package-lock.json',
+    'npm-debug.log'
+  ];
+
+  return ignoredNames.some(ignored => path.includes(ignored));
+}
+
+/**
+ * Recursively get all files in a directory
+ */
+function getAllFiles(dir: string, baseDir: string = dir): string[] {
+  if (!existsSync(dir)) {
+    return [];
+  }
+
+  const files: string[] = [];
+  const entries = readdirSync(dir);
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry);
+    const relativePath = relative(baseDir, fullPath);
+
+    if (shouldIgnore(relativePath)) {
+      continue;
+    }
+
+    const stat = statSync(fullPath);
+
+    if (stat.isDirectory()) {
+      files.push(...getAllFiles(fullPath, baseDir));
+    } else if (stat.isFile()) {
+      files.push(relativePath);
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Compare two directories and return differences
+ * @param actualDir - Directory with actual output
+ * @param expectedDir - Directory with expected output (gold files)
+ * @returns Array of differences (empty if identical)
+ */
+export function compareDirectories(actualDir: string, expectedDir: string): FileDifference[] {
+  const differences: FileDifference[] = [];
+
+  // Get all files from both directories
+  const actualFiles = new Set(getAllFiles(actualDir));
+  const expectedFiles = new Set(getAllFiles(expectedDir));
+
+  // Check for missing files (in expected but not in actual)
+  for (const file of expectedFiles) {
+    if (!actualFiles.has(file)) {
+      differences.push({
+        type: 'missing',
+        path: file,
+        details: `File exists in gold but not in actual output`
+      });
+    }
+  }
+
+  // Check for extra files (in actual but not in expected)
+  for (const file of actualFiles) {
+    if (!expectedFiles.has(file)) {
+      differences.push({
+        type: 'extra',
+        path: file,
+        details: `File exists in actual output but not in gold`
+      });
+    }
+  }
+
+  // Compare content of common files
+  for (const file of actualFiles) {
+    if (!expectedFiles.has(file)) {
+      continue; // Already reported as extra
+    }
+
+    const actualPath = join(actualDir, file);
+    const expectedPath = join(expectedDir, file);
+
+    const actualStat = statSync(actualPath);
+    const expectedStat = statSync(expectedPath);
+
+    // Check if both are same type (file vs directory)
+    if (actualStat.isDirectory() !== expectedStat.isDirectory()) {
+      differences.push({
+        type: 'type-mismatch',
+        path: file,
+        details: actualStat.isDirectory()
+          ? 'Actual is directory but expected is file'
+          : 'Actual is file but expected is directory'
+      });
+      continue;
+    }
+
+    // Compare file contents
+    if (actualStat.isFile()) {
+      const actualContent = normalizeContent(readFileSync(actualPath, 'utf-8'));
+      const expectedContent = normalizeContent(readFileSync(expectedPath, 'utf-8'));
+
+      if (actualContent !== expectedContent) {
+        // Generate a simple diff preview
+        const actualLines = actualContent.split('\n');
+        const expectedLines = expectedContent.split('\n');
+        const maxLines = Math.max(actualLines.length, expectedLines.length);
+        let diffPreview = '';
+
+        for (let i = 0; i < Math.min(5, maxLines); i++) {
+          if (actualLines[i] !== expectedLines[i]) {
+            diffPreview += `\n  Line ${i + 1}:\n`;
+            diffPreview += `    Expected: ${expectedLines[i] || '(empty)'}\n`;
+            diffPreview += `    Actual:   ${actualLines[i] || '(empty)'}`;
+            break; // Show first difference only
+          }
+        }
+
+        differences.push({
+          type: 'content',
+          path: file,
+          details: `File contents differ${diffPreview}`
+        });
+      }
+    }
+  }
+
+  return differences;
+}
+
+/**
+ * Update gold files with actual output
+ * Use with UPDATE_GOLD=1 environment variable
+ */
+export function updateGoldFiles(actualDir: string, goldDir: string): void {
+  if (!existsSync(actualDir)) {
+    throw new Error(`Actual directory does not exist: ${actualDir}`);
+  }
+
+  // Remove existing gold directory
+  if (existsSync(goldDir)) {
+    rmSync(goldDir, { recursive: true, force: true });
+  }
+
+  // Create gold directory
+  mkdirSync(goldDir, { recursive: true });
+
+  // Copy actual output to gold
+  cpSync(actualDir, goldDir, {
+    recursive: true,
+    filter: (src) => {
+      const relativePath = relative(actualDir, src);
+      return !shouldIgnore(relativePath);
+    }
+  });
+
+  console.warn(`⚠️  Updated gold files: ${goldDir}`);
+}
+
+/**
+ * Compare or update gold files based on UPDATE_GOLD environment variable
+ */
+export function compareOrUpdate(actualDir: string, goldDir: string): FileDifference[] {
+  if (process.env.UPDATE_GOLD === '1') {
+    updateGoldFiles(actualDir, goldDir);
+    return []; // Return no differences when updating
+  }
+
+  return compareDirectories(actualDir, goldDir);
+}

package/test/helpers/create-temp-dir.ts

@@ -0,0 +1,34 @@
+import { mkdtempSync, rmSync, existsSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+/**
+ * Create a temporary directory for testing
+ * @returns Absolute path to the temporary directory
+ */
+export function createTempDir(): string {
+  const prefix = join(tmpdir(), 'cli-test-');
+  return mkdtempSync(prefix);
+}
+
+/**
+ * Clean up a temporary directory
+ * @param tempDir - Path to the temporary directory to remove
+ */
+export function cleanupTempDir(tempDir: string): void {
+  if (existsSync(tempDir)) {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Create a temporary directory and return cleanup function
+ * Use with afterEach: const cleanup = useTempDir();
+ */
+export function useTempDir(): { path: string; cleanup: () => void } {
+  const tempDir = createTempDir();
+  return {
+    path: tempDir,
+    cleanup: () => cleanupTempDir(tempDir)
+  };
+}

package/test/helpers/fixtures.ts

@@ -0,0 +1,67 @@
+import { cpSync, existsSync } from 'fs';
+import { join, resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Get the absolute path to the test directory
+ */
+export function getTestDir(): string {
+  return resolve(__dirname, '..');
+}
+
+/**
+ * Get the absolute path to a fixture
+ */
+export function getFixturePath(fixtureName: string): string {
+  return join(getTestDir(), 'e2e', 'fixtures', fixtureName);
+}
+
+/**
+ * Get the absolute path to a gold file directory
+ */
+export function getGoldPath(goldName: string): string {
+  return join(getTestDir(), 'e2e', 'gold', goldName);
+}
+
+/**
+ * Get the absolute path to a unit test gold file
+ */
+export function getUnitGoldPath(category: string, filename: string): string {
+  return join(getTestDir(), 'unit', 'gold', category, filename);
+}
+
+/**
+ * Copy a fixture to a target directory
+ * @param fixtureName - Name of the fixture in test/e2e/fixtures/
+ * @param targetPath - Absolute path where to copy the fixture
+ * @returns The target path
+ */
+export function copyFixture(fixtureName: string, targetPath: string): string {
+  const fixturePath = getFixturePath(fixtureName);
+
+  if (!existsSync(fixturePath)) {
+    throw new Error(`Fixture not found: ${fixturePath}`);
+  }
+
+  cpSync(fixturePath, targetPath, {
+    recursive: true,
+    filter: (src) => {
+      // Don't copy node_modules or dist directories
+      return !src.includes('node_modules') && !src.includes('dist');
+    }
+  });
+
+  return targetPath;
+}
+
+/**
+ * Read a gold file's content
+ */
+export function readGoldFile(category: string, filename: string): string {
+  const { readFileSync } = require('fs');
+  const goldPath = getUnitGoldPath(category, filename);
+  return readFileSync(goldPath, 'utf-8');
+}

package/test/setup.ts

@@ -0,0 +1,6 @@
+/**
+ * Global test setup for Vitest
+ * This file runs before all tests
+ */
+
+// Add any global test utilities or setup here