@magentrix-corp/magentrix-cli 1.3.16 → 1.3.17

package/utils/iris/builder.js

@@ -1,541 +1,541 @@
-import { spawn } from 'node:child_process';
-import { existsSync, mkdirSync, cpSync, rmSync, readdirSync, statSync } from 'node:fs';
-import { join, resolve, basename } from 'node:path';
-import { validateIrisBuild } from './validator.js';
-import { updateLastBuild } from './linker.js';
-import { EXPORT_ROOT, IRIS_APPS_DIR } from '../../vars/global.js';
-import { detectErrorType, ErrorTypes, formatPermissionError, formatDiskFullError, formatFileLockError } from './errors.js';
-import { acquireLock, releaseLock, LockTypes, createProjectContext } from './lock.js';
-
-// Files to exclude when staging Iris apps (not needed on server)
-const EXCLUDED_FILES = new Set([
-    'index.html',
-    'favicon.ico',
-    '.DS_Store',
-    'Thumbs.db',
-    '.gitignore',
-    '.gitkeep'
-]);
-
-/**
- * Maximum dist folder size before warning (500MB)
- */
-const MAX_DIST_SIZE_WARNING = 500 * 1024 * 1024;
-
-/**
- * Build a Vue project using npm run build.
- *
- * @param {string} projectPath - Path to the Vue project
- * @param {Object} options - Build options
- * @param {boolean} options.silent - Suppress build output
- * @returns {Promise<{
- *   success: boolean,
- *   output: string,
- *   error: string | null,
- *   distPath: string | null,
- *   warnings: string[]
- * }>}
- */
-export async function buildVueProject(projectPath, options = {}) {
-    const { silent = false } = options;
-    const resolvedPath = resolve(projectPath);
-    const warnings = [];
-
-    // Check for package.json
-    if (!existsSync(join(resolvedPath, 'package.json'))) {
-        return {
-            success: false,
-            output: '',
-            error: `No package.json found in ${resolvedPath}`,
-            distPath: null,
-            warnings
-        };
-    }
-
-    // Check for node_modules
-    if (!existsSync(join(resolvedPath, 'node_modules'))) {
-        return {
-            success: false,
-            output: '',
-            error: `No node_modules found.\n\nRun the following command first:\n  cd "${resolvedPath}"\n  npm install`,
-            distPath: null,
-            warnings
-        };
-    }
-
-    // Acquire build lock to prevent concurrent builds
-    // Use os.tmpdir() as basePath to avoid permission issues in project directories
-    const lockContext = createProjectContext(resolvedPath);
-    const lockResult = acquireLock(LockTypes.BUILD, {
-        context: lockContext,
-        operation: `building ${basename(resolvedPath)}`,
-        basePath: join(process.env.HOME || process.env.USERPROFILE || '/tmp', '.magentrix-locks')
-    });
-
-    // If lock acquisition fails due to permissions, warn but continue
-    // (locking is nice-to-have, not critical for builds)
-    let lockAcquired = lockResult.acquired;
-    if (!lockResult.acquired) {
-        // Check if it's a permission error vs actual concurrent operation
-        if (lockResult.error?.includes('permission') || lockResult.error?.includes('EACCES')) {
-            warnings.push('Could not create build lock (permission issue). Proceeding without lock.');
-            lockAcquired = false;
-        } else {
-            // Actual concurrent operation - fail
-            return {
-                success: false,
-                output: '',
-                error: lockResult.error,
-                distPath: null,
-                warnings
-            };
-        }
-    }
-
-    try {
-        return await new Promise((resolvePromise) => {
-            const output = [];
-            const errorOutput = [];
-
-            // Determine npm command based on platform
-            const isWindows = process.platform === 'win32';
-            const npmCmd = isWindows ? 'npm.cmd' : 'npm';
-
-            const child = spawn(npmCmd, ['run', 'build'], {
-                cwd: resolvedPath,
-                shell: isWindows,  // Windows requires shell: true for .cmd files
-                env: { ...process.env, FORCE_COLOR: '1' }
-            });
-
-            child.stdout.on('data', (data) => {
-                const text = data.toString();
-                output.push(text);
-                if (!silent) {
-                    process.stdout.write(text);
-                }
-            });
-
-            child.stderr.on('data', (data) => {
-                const text = data.toString();
-                errorOutput.push(text);
-                if (!silent) {
-                    process.stderr.write(text);
-                }
-            });
-
-            child.on('close', (code) => {
-                const fullOutput = output.join('');
-                const fullError = errorOutput.join('');
-
-                if (code !== 0) {
-                    resolvePromise({
-                        success: false,
-                        output: fullOutput,
-                        error: fullError || `Build process exited with code ${code}`,
-                        distPath: null,
-                        warnings
-                    });
-                    return;
-                }
-
-                // Find dist directory (Vue typically outputs to 'dist')
-                const possibleDistPaths = ['dist', 'build', 'output'];
-                let distPath = null;
-
-                for (const distDir of possibleDistPaths) {
-                    const fullPath = join(resolvedPath, distDir);
-                    if (existsSync(fullPath)) {
-                        distPath = fullPath;
-                        break;
-                    }
-                }
-
-                if (!distPath) {
-                    resolvePromise({
-                        success: false,
-                        output: fullOutput,
-                        error: 'Build completed but no dist/build directory found.\n\n' +
-                               'Expected one of: dist/, build/, or output/',
-                        distPath: null,
-                        warnings
-                    });
-                    return;
-                }
-
-                // Check dist folder size
-                const distSize = getDirectorySize(distPath);
-                if (distSize > MAX_DIST_SIZE_WARNING) {
-                    const sizeMB = Math.round(distSize / (1024 * 1024));
-                    warnings.push(`Large build output (${sizeMB}MB). This may take longer to stage and publish.`);
-                }
-
-                resolvePromise({
-                    success: true,
-                    output: fullOutput,
-                    error: null,
-                    distPath,
-                    warnings
-                });
-            });
-
-            child.on('error', (err) => {
-                resolvePromise({
-                    success: false,
-                    output: output.join(''),
-                    error: `Failed to start build process: ${err.message}`,
-                    distPath: null,
-                    warnings
-                });
-            });
-        });
-    } finally {
-        // Release the lock only if we acquired it
-        if (lockAcquired) {
-            releaseLock(LockTypes.BUILD, {
-                context: lockContext,
-                basePath: join(process.env.HOME || process.env.USERPROFILE || '/tmp', '.magentrix-locks')
-            });
-        }
-    }
-}
-
-/**
- * Calculate total size of a directory recursively.
- *
- * @param {string} dirPath - Directory path
- * @returns {number} - Total size in bytes
- */
-function getDirectorySize(dirPath) {
-    let totalSize = 0;
-
-    try {
-        const items = readdirSync(dirPath, { withFileTypes: true });
-        for (const item of items) {
-            const itemPath = join(dirPath, item.name);
-            if (item.isDirectory()) {
-                totalSize += getDirectorySize(itemPath);
-            } else {
-                try {
-                    const stats = statSync(itemPath);
-                    totalSize += stats.size;
-                } catch {
-                    // Skip files we can't stat
-                }
-            }
-        }
-    } catch {
-        // Return what we have so far
-    }
-
-    return totalSize;
-}
-
-/**
- * Stage build output to a Magentrix workspace's iris-apps directory.
- *
- * @param {string} distPath - Path to the build output (dist directory)
- * @param {string} slug - The app slug (folder name)
- * @param {string} workspacePath - Path to the Magentrix workspace (defaults to CWD)
- * @returns {{
- *   success: boolean,
- *   stagedPath: string | null,
- *   error: string | null,
- *   fileCount: number,
- *   warnings: string[]
- * }}
- */
-export function stageToWorkspace(distPath, slug, workspacePath = process.cwd()) {
-    const resolvedDistPath = resolve(distPath);
-    const irisAppsDir = join(workspacePath, EXPORT_ROOT, IRIS_APPS_DIR);
-    const targetDir = join(irisAppsDir, slug);
-    const warnings = [];
-
-    // Validate dist path exists
-    if (!existsSync(resolvedDistPath)) {
-        return {
-            success: false,
-            stagedPath: null,
-            error: `Dist path does not exist: ${resolvedDistPath}\n\n` +
-                   `The source folder may have been deleted or moved.`,
-            fileCount: 0,
-            warnings
-        };
-    }
-
-    // Validate build output
-    const validation = validateIrisBuild(resolvedDistPath);
-    if (!validation.valid) {
-        return {
-            success: false,
-            stagedPath: null,
-            error: `Invalid build output:\n${validation.errors.join('\n')}`,
-            fileCount: 0,
-            warnings
-        };
-    }
-
-    // Acquire staging lock (use user home for consistent lock location)
-    const lockBasePath = join(process.env.HOME || process.env.USERPROFILE || '/tmp', '.magentrix-locks');
-    const lockResult = acquireLock(LockTypes.STAGE, {
-        context: slug,
-        operation: `staging ${slug}`,
-        basePath: lockBasePath
-    });
-
-    // If lock acquisition fails due to permissions, warn but continue
-    let lockAcquired = lockResult.acquired;
-    if (!lockResult.acquired) {
-        if (lockResult.error?.includes('permission') || lockResult.error?.includes('EACCES')) {
-            warnings.push('Could not create staging lock (permission issue). Proceeding without lock.');
-            lockAcquired = false;
-        } else {
-            return {
-                success: false,
-                stagedPath: null,
-                error: lockResult.error,
-                fileCount: 0,
-                warnings
-            };
-        }
-    }
-
-    try {
-        // Ensure iris-apps directory exists
-        try {
-            if (!existsSync(irisAppsDir)) {
-                mkdirSync(irisAppsDir, { recursive: true });
-            }
-        } catch (err) {
-            const errorType = detectErrorType(err);
-            if (errorType === ErrorTypes.PERMISSION) {
-                return {
-                    success: false,
-                    stagedPath: null,
-                    error: formatPermissionError({
-                        operation: 'create directory',
-                        path: irisAppsDir
-                    }),
-                    fileCount: 0,
-                    warnings
-                };
-            }
-            return {
-                success: false,
-                stagedPath: null,
-                error: `Failed to create iris-apps directory: ${err.message}`,
-                fileCount: 0,
-                warnings
-            };
-        }
-
-        // Remove existing app directory if it exists
-        if (existsSync(targetDir)) {
-            try {
-                rmSync(targetDir, { recursive: true, force: true });
-            } catch (err) {
-                const errorType = detectErrorType(err);
-                if (errorType === ErrorTypes.PERMISSION) {
-                    return {
-                        success: false,
-                        stagedPath: null,
-                        error: formatPermissionError({
-                            operation: 'remove existing directory',
-                            path: targetDir
-                        }),
-                        fileCount: 0,
-                        warnings
-                    };
-                }
-                if (errorType === ErrorTypes.FILE_LOCKED) {
-                    return {
-                        success: false,
-                        stagedPath: null,
-                        error: formatFileLockError({ path: targetDir }),
-                        fileCount: 0,
-                        warnings
-                    };
-                }
-                return {
-                    success: false,
-                    stagedPath: null,
-                    error: `Failed to remove existing app directory: ${err.message}`,
-                    fileCount: 0,
-                    warnings
-                };
-            }
-        }
-
-        // Copy dist contents to target, excluding unnecessary files
-        try {
-            cpSync(resolvedDistPath, targetDir, {
-                recursive: true,
-                filter: (src) => {
-                    // Use basename for reliable cross-platform filename extraction
-                    const filename = basename(src);
-                    // Only exclude specific files, not directories
-                    if (EXCLUDED_FILES.has(filename)) {
-                        return false;
-                    }
-                    return true;
-                }
-            });
-        } catch (err) {
-            const errorType = detectErrorType(err);
-            if (errorType === ErrorTypes.PERMISSION) {
-                return {
-                    success: false,
-                    stagedPath: null,
-                    error: formatPermissionError({
-                        operation: 'copy files',
-                        path: targetDir
-                    }),
-                    fileCount: 0,
-                    warnings
-                };
-            }
-            if (errorType === ErrorTypes.DISK_FULL) {
-                return {
-                    success: false,
-                    stagedPath: null,
-                    error: formatDiskFullError({
-                        operation: 'copy build files',
-                        path: targetDir
-                    }),
-                    fileCount: 0,
-                    warnings
-                };
-            }
-            return {
-                success: false,
-                stagedPath: null,
-                error: `Failed to copy build output: ${err.message}`,
-                fileCount: 0,
-                warnings
-            };
-        }
-
-        // Count files copied
-        const fileCount = countFiles(targetDir);
-
-        // Update last build timestamp for linked project (ignore errors)
-        const updateResult = updateLastBuild(slug);
-        if (!updateResult.success && updateResult.error) {
-            warnings.push(`Could not update last build timestamp: ${updateResult.error}`);
-        }
-
-        return {
-            success: true,
-            stagedPath: targetDir,
-            error: null,
-            fileCount,
-            warnings
-        };
-    } finally {
-        // Release the lock only if we acquired it
-        if (lockAcquired) {
-            releaseLock(LockTypes.STAGE, { context: slug, basePath: lockBasePath });
-        }
-    }
-}
-
-/**
- * Count files recursively in a directory.
- *
- * @param {string} dir - Directory to count files in
- * @returns {number} - Number of files
- */
-function countFiles(dir) {
-    if (!existsSync(dir)) return 0;
-
-    let count = 0;
-    const items = readdirSync(dir, { withFileTypes: true });
-
-    for (const item of items) {
-        if (item.isDirectory()) {
-            count += countFiles(join(dir, item.name));
-        } else {
-            count++;
-        }
-    }
-
-    return count;
-}
-
-/**
- * Find an existing dist directory in a Vue project.
- *
- * @param {string} projectPath - Path to the Vue project
- * @returns {string | null} - Path to dist directory or null if not found
- */
-export function findDistDirectory(projectPath) {
-    const possibleDistPaths = ['dist', 'build', 'output'];
-
-    for (const distDir of possibleDistPaths) {
-        const fullPath = join(projectPath, distDir);
-        if (existsSync(fullPath)) {
-            return fullPath;
-        }
-    }
-
-    return null;
-}
-
-/**
- * Format build error for display.
- *
- * @param {string} projectPath - Path to the Vue project
- * @param {string} errorOutput - Error output from build
- * @returns {string} - Formatted error message
- */
-export function formatBuildError(projectPath, errorOutput) {
-    return `Build Failed
-────────────────────────────────────────────────────
-
-The Vue.js build process failed. This is a project issue, not a CLI issue.
-
-Error output:
-${errorOutput.split('\n').map(line => `  ${line}`).join('\n')}
-
-To fix this:
-  1. Run 'npm run build' manually in your Vue project:
-     cd ${projectPath}
-     npm run build
-
-  2. Fix any compilation errors shown above
-
-  3. Run 'magentrix vue-run-build' again
-
-Alternatively, use --skip-build to stage an existing dist/ folder.`;
-}
-
-/**
- * Format validation error for display.
- *
- * @param {string} distPath - Path to the dist directory
- * @param {string[]} errors - Validation errors
- * @returns {string} - Formatted error message
- */
-export function formatValidationError(distPath, errors) {
-    return `Invalid Build Output
-────────────────────────────────────────────────────
-
-The build output at ${distPath} is missing required files.
-
-Missing:
-${errors.map(e => `  ✗ ${e}`).join('\n')}
-
-Required files for an Iris app:
-  - remoteEntry.js (Module Federation entry point)
-  - assets/hostInit*.js (Host initialization script)
-  - assets/main*.js (Main entry point)
-  - assets/index*.js (Index entry)
-
-This usually means:
-  1. The project is not configured as a Module Federation remote
-  2. The build did not complete successfully
-  3. The dist directory contains an old or incorrect build
-
-Try rebuilding the project:
-  cd ${distPath.replace('/dist', '')}
-  npm run build`;
-}
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, cpSync, rmSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve, basename } from 'node:path';
+import { validateIrisBuild } from './validator.js';
+import { updateLastBuild } from './linker.js';
+import { EXPORT_ROOT, IRIS_APPS_DIR } from '../../vars/global.js';
+import { detectErrorType, ErrorTypes, formatPermissionError, formatDiskFullError, formatFileLockError } from './errors.js';
+import { acquireLock, releaseLock, LockTypes, createProjectContext } from './lock.js';
+
+// Files to exclude when staging Iris apps (not needed on server)
+const EXCLUDED_FILES = new Set([
+    'index.html',
+    'favicon.ico',
+    '.DS_Store',
+    'Thumbs.db',
+    '.gitignore',
+    '.gitkeep'
+]);
+
+/**
+ * Maximum dist folder size before warning (500MB)
+ */
+const MAX_DIST_SIZE_WARNING = 500 * 1024 * 1024;
+
+/**
+ * Build a Vue project using npm run build.
+ *
+ * @param {string} projectPath - Path to the Vue project
+ * @param {Object} options - Build options
+ * @param {boolean} options.silent - Suppress build output
+ * @returns {Promise<{
+ *   success: boolean,
+ *   output: string,
+ *   error: string | null,
+ *   distPath: string | null,
+ *   warnings: string[]
+ * }>}
+ */
+export async function buildVueProject(projectPath, options = {}) {
+    const { silent = false } = options;
+    const resolvedPath = resolve(projectPath);
+    const warnings = [];
+
+    // Check for package.json
+    if (!existsSync(join(resolvedPath, 'package.json'))) {
+        return {
+            success: false,
+            output: '',
+            error: `No package.json found in ${resolvedPath}`,
+            distPath: null,
+            warnings
+        };
+    }
+
+    // Check for node_modules
+    if (!existsSync(join(resolvedPath, 'node_modules'))) {
+        return {
+            success: false,
+            output: '',
+            error: `No node_modules found.\n\nRun the following command first:\n  cd "${resolvedPath}"\n  npm install`,
+            distPath: null,
+            warnings
+        };
+    }
+
+    // Acquire build lock to prevent concurrent builds
+    // Use os.tmpdir() as basePath to avoid permission issues in project directories
+    const lockContext = createProjectContext(resolvedPath);
+    const lockResult = acquireLock(LockTypes.BUILD, {
+        context: lockContext,
+        operation: `building ${basename(resolvedPath)}`,
+        basePath: join(process.env.HOME || process.env.USERPROFILE || '/tmp', '.magentrix-locks')
+    });
+
+    // If lock acquisition fails due to permissions, warn but continue
+    // (locking is nice-to-have, not critical for builds)
+    let lockAcquired = lockResult.acquired;
+    if (!lockResult.acquired) {
+        // Check if it's a permission error vs actual concurrent operation
+        if (lockResult.error?.includes('permission') || lockResult.error?.includes('EACCES')) {
+            warnings.push('Could not create build lock (permission issue). Proceeding without lock.');
+            lockAcquired = false;
+        } else {
+            // Actual concurrent operation - fail
+            return {
+                success: false,
+                output: '',
+                error: lockResult.error,
+                distPath: null,
+                warnings
+            };
+        }
+    }
+
+    try {
+        return await new Promise((resolvePromise) => {
+            const output = [];
+            const errorOutput = [];
+
+            // Determine npm command based on platform
+            const isWindows = process.platform === 'win32';
+            const npmCmd = isWindows ? 'npm.cmd' : 'npm';
+
+            const child = spawn(npmCmd, ['run', 'build'], {
+                cwd: resolvedPath,
+                shell: isWindows,  // Windows requires shell: true for .cmd files
+                env: { ...process.env, FORCE_COLOR: '1' }
+            });
+
+            child.stdout.on('data', (data) => {
+                const text = data.toString();
+                output.push(text);
+                if (!silent) {
+                    process.stdout.write(text);
+                }
+            });
+
+            child.stderr.on('data', (data) => {
+                const text = data.toString();
+                errorOutput.push(text);
+                if (!silent) {
+                    process.stderr.write(text);
+                }
+            });
+
+            child.on('close', (code) => {
+                const fullOutput = output.join('');
+                const fullError = errorOutput.join('');
+
+                if (code !== 0) {
+                    resolvePromise({
+                        success: false,
+                        output: fullOutput,
+                        error: fullError || `Build process exited with code ${code}`,
+                        distPath: null,
+                        warnings
+                    });
+                    return;
+                }
+
+                // Find dist directory (Vue typically outputs to 'dist')
+                const possibleDistPaths = ['dist', 'build', 'output'];
+                let distPath = null;
+
+                for (const distDir of possibleDistPaths) {
+                    const fullPath = join(resolvedPath, distDir);
+                    if (existsSync(fullPath)) {
+                        distPath = fullPath;
+                        break;
+                    }
+                }
+
+                if (!distPath) {
+                    resolvePromise({
+                        success: false,
+                        output: fullOutput,
+                        error: 'Build completed but no dist/build directory found.\n\n' +
+                               'Expected one of: dist/, build/, or output/',
+                        distPath: null,
+                        warnings
+                    });
+                    return;
+                }
+
+                // Check dist folder size
+                const distSize = getDirectorySize(distPath);
+                if (distSize > MAX_DIST_SIZE_WARNING) {
+                    const sizeMB = Math.round(distSize / (1024 * 1024));
+                    warnings.push(`Large build output (${sizeMB}MB). This may take longer to stage and publish.`);
+                }
+
+                resolvePromise({
+                    success: true,
+                    output: fullOutput,
+                    error: null,
+                    distPath,
+                    warnings
+                });
+            });
+
+            child.on('error', (err) => {
+                resolvePromise({
+                    success: false,
+                    output: output.join(''),
+                    error: `Failed to start build process: ${err.message}`,
+                    distPath: null,
+                    warnings
+                });
+            });
+        });
+    } finally {
+        // Release the lock only if we acquired it
+        if (lockAcquired) {
+            releaseLock(LockTypes.BUILD, {
+                context: lockContext,
+                basePath: join(process.env.HOME || process.env.USERPROFILE || '/tmp', '.magentrix-locks')
+            });
+        }
+    }
+}
+
+/**
+ * Calculate total size of a directory recursively.
+ *
+ * @param {string} dirPath - Directory path
+ * @returns {number} - Total size in bytes
+ */
+function getDirectorySize(dirPath) {
+    let totalSize = 0;
+
+    try {
+        const items = readdirSync(dirPath, { withFileTypes: true });
+        for (const item of items) {
+            const itemPath = join(dirPath, item.name);
+            if (item.isDirectory()) {
+                totalSize += getDirectorySize(itemPath);
+            } else {
+                try {
+                    const stats = statSync(itemPath);
+                    totalSize += stats.size;
+                } catch {
+                    // Skip files we can't stat
+                }
+            }
+        }
+    } catch {
+        // Return what we have so far
+    }
+
+    return totalSize;
+}
+
+/**
+ * Stage build output to a Magentrix workspace's iris-apps directory.
+ *
+ * @param {string} distPath - Path to the build output (dist directory)
+ * @param {string} slug - The app slug (folder name)
+ * @param {string} workspacePath - Path to the Magentrix workspace (defaults to CWD)
+ * @returns {{
+ *   success: boolean,
+ *   stagedPath: string | null,
+ *   error: string | null,
+ *   fileCount: number,
+ *   warnings: string[]
+ * }}
+ */
+export function stageToWorkspace(distPath, slug, workspacePath = process.cwd()) {
+    const resolvedDistPath = resolve(distPath);
+    const irisAppsDir = join(workspacePath, EXPORT_ROOT, IRIS_APPS_DIR);
+    const targetDir = join(irisAppsDir, slug);
+    const warnings = [];
+
+    // Validate dist path exists
+    if (!existsSync(resolvedDistPath)) {
+        return {
+            success: false,
+            stagedPath: null,
+            error: `Dist path does not exist: ${resolvedDistPath}\n\n` +
+                   `The source folder may have been deleted or moved.`,
+            fileCount: 0,
+            warnings
+        };
+    }
+
+    // Validate build output
+    const validation = validateIrisBuild(resolvedDistPath);
+    if (!validation.valid) {
+        return {
+            success: false,
+            stagedPath: null,
+            error: `Invalid build output:\n${validation.errors.join('\n')}`,
+            fileCount: 0,
+            warnings
+        };
+    }
+
+    // Acquire staging lock (use user home for consistent lock location)
+    const lockBasePath = join(process.env.HOME || process.env.USERPROFILE || '/tmp', '.magentrix-locks');
+    const lockResult = acquireLock(LockTypes.STAGE, {
+        context: slug,
+        operation: `staging ${slug}`,
+        basePath: lockBasePath
+    });
+
+    // If lock acquisition fails due to permissions, warn but continue
+    let lockAcquired = lockResult.acquired;
+    if (!lockResult.acquired) {
+        if (lockResult.error?.includes('permission') || lockResult.error?.includes('EACCES')) {
+            warnings.push('Could not create staging lock (permission issue). Proceeding without lock.');
+            lockAcquired = false;
+        } else {
+            return {
+                success: false,
+                stagedPath: null,
+                error: lockResult.error,
+                fileCount: 0,
+                warnings
+            };
+        }
+    }
+
+    try {
+        // Ensure iris-apps directory exists
+        try {
+            if (!existsSync(irisAppsDir)) {
+                mkdirSync(irisAppsDir, { recursive: true });
+            }
+        } catch (err) {
+            const errorType = detectErrorType(err);
+            if (errorType === ErrorTypes.PERMISSION) {
+                return {
+                    success: false,
+                    stagedPath: null,
+                    error: formatPermissionError({
+                        operation: 'create directory',
+                        path: irisAppsDir
+                    }),
+                    fileCount: 0,
+                    warnings
+                };
+            }
+            return {
+                success: false,
+                stagedPath: null,
+                error: `Failed to create iris-apps directory: ${err.message}`,
+                fileCount: 0,
+                warnings
+            };
+        }
+
+        // Remove existing app directory if it exists
+        if (existsSync(targetDir)) {
+            try {
+                rmSync(targetDir, { recursive: true, force: true });
+            } catch (err) {
+                const errorType = detectErrorType(err);
+                if (errorType === ErrorTypes.PERMISSION) {
+                    return {
+                        success: false,
+                        stagedPath: null,
+                        error: formatPermissionError({
+                            operation: 'remove existing directory',
+                            path: targetDir
+                        }),
+                        fileCount: 0,
+                        warnings
+                    };
+                }
+                if (errorType === ErrorTypes.FILE_LOCKED) {
+                    return {
+                        success: false,
+                        stagedPath: null,
+                        error: formatFileLockError({ path: targetDir }),
+                        fileCount: 0,
+                        warnings
+                    };
+                }
+                return {
+                    success: false,
+                    stagedPath: null,
+                    error: `Failed to remove existing app directory: ${err.message}`,
+                    fileCount: 0,
+                    warnings
+                };
+            }
+        }
+
+        // Copy dist contents to target, excluding unnecessary files
+        try {
+            cpSync(resolvedDistPath, targetDir, {
+                recursive: true,
+                filter: (src) => {
+                    // Use basename for reliable cross-platform filename extraction
+                    const filename = basename(src);
+                    // Only exclude specific files, not directories
+                    if (EXCLUDED_FILES.has(filename)) {
+                        return false;
+                    }
+                    return true;
+                }
+            });
+        } catch (err) {
+            const errorType = detectErrorType(err);
+            if (errorType === ErrorTypes.PERMISSION) {
+                return {
+                    success: false,
+                    stagedPath: null,
+                    error: formatPermissionError({
+                        operation: 'copy files',
+                        path: targetDir
+                    }),
+                    fileCount: 0,
+                    warnings
+                };
+            }
+            if (errorType === ErrorTypes.DISK_FULL) {
+                return {
+                    success: false,
+                    stagedPath: null,
+                    error: formatDiskFullError({
+                        operation: 'copy build files',
+                        path: targetDir
+                    }),
+                    fileCount: 0,
+                    warnings
+                };
+            }
+            return {
+                success: false,
+                stagedPath: null,
+                error: `Failed to copy build output: ${err.message}`,
+                fileCount: 0,
+                warnings
+            };
+        }
+
+        // Count files copied
+        const fileCount = countFiles(targetDir);
+
+        // Update last build timestamp for linked project (ignore errors)
+        const updateResult = updateLastBuild(slug);
+        if (!updateResult.success && updateResult.error) {
+            warnings.push(`Could not update last build timestamp: ${updateResult.error}`);
+        }
+
+        return {
+            success: true,
+            stagedPath: targetDir,
+            error: null,
+            fileCount,
+            warnings
+        };
+    } finally {
+        // Release the lock only if we acquired it
+        if (lockAcquired) {
+            releaseLock(LockTypes.STAGE, { context: slug, basePath: lockBasePath });
+        }
+    }
+}
+
+/**
+ * Count files recursively in a directory.
+ *
+ * @param {string} dir - Directory to count files in
+ * @returns {number} - Number of files
+ */
+function countFiles(dir) {
+    if (!existsSync(dir)) return 0;
+
+    let count = 0;
+    const items = readdirSync(dir, { withFileTypes: true });
+
+    for (const item of items) {
+        if (item.isDirectory()) {
+            count += countFiles(join(dir, item.name));
+        } else {
+            count++;
+        }
+    }
+
+    return count;
+}
+
+/**
+ * Find an existing dist directory in a Vue project.
+ *
+ * @param {string} projectPath - Path to the Vue project
+ * @returns {string | null} - Path to dist directory or null if not found
+ */
+export function findDistDirectory(projectPath) {
+    const possibleDistPaths = ['dist', 'build', 'output'];
+
+    for (const distDir of possibleDistPaths) {
+        const fullPath = join(projectPath, distDir);
+        if (existsSync(fullPath)) {
+            return fullPath;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Format build error for display.
+ *
+ * @param {string} projectPath - Path to the Vue project
+ * @param {string} errorOutput - Error output from build
+ * @returns {string} - Formatted error message
+ */
+export function formatBuildError(projectPath, errorOutput) {
+    return `Build Failed
+────────────────────────────────────────────────────
+
+The Vue.js build process failed. This is a project issue, not a CLI issue.
+
+Error output:
+${errorOutput.split('\n').map(line => `  ${line}`).join('\n')}
+
+To fix this:
+  1. Run 'npm run build' manually in your Vue project:
+     cd ${projectPath}
+     npm run build
+
+  2. Fix any compilation errors shown above
+
+  3. Run 'magentrix vue-run-build' again
+
+Alternatively, use --skip-build to stage an existing dist/ folder.`;
+}
+
+/**
+ * Format validation error for display.
+ *
+ * @param {string} distPath - Path to the dist directory
+ * @param {string[]} errors - Validation errors
+ * @returns {string} - Formatted error message
+ */
+export function formatValidationError(distPath, errors) {
+    return `Invalid Build Output
+────────────────────────────────────────────────────
+
+The build output at ${distPath} is missing required files.
+
+Missing:
+${errors.map(e => `  ✗ ${e}`).join('\n')}
+
+Required files for an Iris app:
+  - remoteEntry.js (Module Federation entry point)
+  - assets/hostInit*.js (Host initialization script)
+  - assets/main*.js (Main entry point)
+  - assets/index*.js (Index entry)
+
+This usually means:
+  1. The project is not configured as a Module Federation remote
+  2. The build did not complete successfully
+  3. The dist directory contains an old or incorrect build
+
+Try rebuilding the project:
+  cd ${distPath.replace('/dist', '')}
+  npm run build`;
+}