@magentrix-corp/magentrix-cli 1.3.15 → 1.3.17

package/actions/iris/buildStage.js

@@ -1,874 +1,874 @@
-import chalk from 'chalk';
-import { select, input, confirm } from '@inquirer/prompts';
-import { existsSync } from 'node:fs';
-import { resolve, join } from 'node:path';
-import { spawn } from 'node:child_process';
-import Config from '../../utils/config.js';
-import { runPublish } from '../publish.js';
-import { isAutopublishRunning } from '../../utils/autopublishLock.js';
-import {
-    buildVueProject,
-    stageToWorkspace,
-    findDistDirectory,
-    formatBuildError,
-    formatValidationError
-} from '../../utils/iris/builder.js';
-import { validateIrisBuild } from '../../utils/iris/validator.js';
-import {
-    readVueConfig,
-    formatMissingConfigError,
-    formatConfigErrors
-} from '../../utils/iris/config-reader.js';
-import {
-    getLinkedProjectsWithStatus,
-    linkVueProject,
-    findLinkedProjectByPath,
-    buildProjectChoices
-} from '../../utils/iris/linker.js';
-import { EXPORT_ROOT, IRIS_APPS_DIR, HASHED_CWD } from '../../vars/global.js';
-import { getValidWorkspaces } from '../../utils/workspaces.js';
-import { formatTimeoutError } from '../../utils/iris/errors.js';
-
-const config = new Config();
-
-/**
- * Timeout for status check operations (30 seconds).
- */
-const STATUS_CHECK_TIMEOUT = 30000;
-
-/**
- * Timeout for command execution (5 minutes).
- */
-const COMMAND_TIMEOUT = 5 * 60 * 1000;
-
-/**
- * Display warnings from build/stage operations.
- *
- * @param {string[]} warnings - Array of warning messages
- */
-function displayWarnings(warnings) {
-    if (!warnings || warnings.length === 0) return;
-
-    for (const warning of warnings) {
-        console.log(chalk.yellow(`⚠ ${warning}`));
-    }
-}
-
-/**
- * Check if the current directory is a Vue project (has config.ts).
- * @returns {boolean}
- */
-function isInVueProject() {
-    const configLocations = [
-        'src/config.ts',
-        'config.ts',
-        'src/iris-config.ts',
-        'iris-config.ts'
-    ];
-    return configLocations.some(loc => existsSync(join(process.cwd(), loc)));
-}
-
-/**
- * Check if the current directory appears to be a Magentrix workspace.
- * @returns {boolean} - True if in a Magentrix workspace
- */
-function isMagentrixWorkspace() {
-    const magentrixFolder = join(process.cwd(), '.magentrix');
-    const srcFolder = join(process.cwd(), 'src');
-
-    // Check for .magentrix folder
-    if (!existsSync(magentrixFolder)) return false;
-
-    // Check for src folder (typical workspace structure)
-    if (!existsSync(srcFolder)) return false;
-
-    // Check if credentials are configured (instanceUrl or apiKey in global config)
-    const instanceUrl = config.read('instanceUrl', { global: true, pathHash: HASHED_CWD });
-    const apiKey = config.read('apiKey', { global: true, pathHash: HASHED_CWD });
-
-    return !!(instanceUrl || apiKey);
-}
-
-/**
- * vue-run-build command - Build a Vue project and stage to CLI workspace.
- *
- * Two modes of operation:
- * 1. Run from Magentrix workspace: prompts for which Vue project to build
- * 2. Run from Vue project: prompts for which workspace to stage into
- *
- * Options:
- *   --path <dir>        Specify Vue project path directly
- *   --skip-build        Use existing dist/ without rebuilding
- *   --workspace <dir>   Specify Magentrix workspace path directly
- */
-export const vueBuildStage = async (options = {}) => {
-    process.stdout.write('\x1Bc'); // Clear console
-
-    const { path: pathOption, skipBuild, workspace: workspaceOption } = options;
-
-    // Detect which mode we're in
-    const inVueProject = isInVueProject();
-    const inWorkspace = isMagentrixWorkspace();
-
-    // If run from a Vue project, use reversed logic
-    if (inVueProject && !inWorkspace) {
-        await buildFromVueProject(options);
-        return;
-    }
-
-    // Standard mode: run from workspace, select Vue project
-    // Warn if not in a Magentrix workspace
-    if (!inWorkspace) {
-        console.log(chalk.yellow('⚠ Warning: Magentrix Workspace Not Detected'));
-        console.log(chalk.gray('─'.repeat(48)));
-        console.log(chalk.white('\nThis command should be run from your Magentrix CLI workspace directory.'));
-        console.log(chalk.white('It stages Vue.js build files to ') + chalk.cyan('src/iris-apps/<slug>/'));
-        console.log();
-        console.log(chalk.white('Expected workspace indicators:'));
-        console.log(chalk.gray('  • .magentrix/ folder (config and cache)'));
-        console.log(chalk.gray('  • src/ folder (code files and assets)'));
-        console.log(chalk.gray('  • Magentrix credentials configured'));
-        console.log();
-        console.log(chalk.white('Current directory: ') + chalk.gray(process.cwd()));
-        console.log();
-
-        const shouldContinue = await confirm({
-            message: 'Do you want to continue anyway?',
-            default: false
-        });
-
-        if (!shouldContinue) {
-            console.log(chalk.gray('\nCancelled. Run this command from your Magentrix workspace.'));
-            return;
-        }
-
-        console.log();
-    }
-
-    // Determine which project to build
-    let projectPath = pathOption;
-    let vueConfig = null;
-
-    if (projectPath) {
-        // Path provided via option
-        projectPath = resolve(projectPath);
-
-        if (!existsSync(projectPath)) {
-            console.log(chalk.red(`Error: Path does not exist: ${projectPath}`));
-            return;
-        }
-
-        vueConfig = readVueConfig(projectPath);
-    } else {
-        // Prompt user to select a project
-        const result = await selectProject();
-        if (!result) return; // User cancelled
-
-        projectPath = result.path;
-        vueConfig = result.config;
-    }
-
-    // Validate Vue config
-    if (!vueConfig.found) {
-        console.log(chalk.red(formatMissingConfigError(projectPath)));
-        return;
-    }
-
-    if (vueConfig.errors.length > 0) {
-        console.log(chalk.red(formatConfigErrors(vueConfig)));
-        return;
-    }
-
-    const { slug, appName } = vueConfig;
-
-    console.log(chalk.blue('\nVue Build & Stage'));
-    console.log(chalk.gray('─'.repeat(48)));
-    console.log(chalk.white(`  Project: ${chalk.cyan(appName)} (${slug})`));
-    console.log(chalk.white(`  Path: ${chalk.gray(projectPath)}`));
-    console.log();
-
-    // Ensure project is linked
-    const linked = findLinkedProjectByPath(projectPath);
-    if (!linked) {
-        const shouldLink = await confirm({
-            message: 'This project is not linked. Link it now?',
-            default: true
-        });
-
-        if (shouldLink) {
-            const linkResult = linkVueProject(projectPath);
-            if (!linkResult.success) {
-                console.log(chalk.red(`Failed to link project: ${linkResult.error}`));
-                return;
-            }
-            console.log(chalk.green(`\u2713 Project linked`));
-        }
-    }
-
-    let distPath;
-
-    if (skipBuild) {
-        // Use existing dist
-        distPath = findDistDirectory(projectPath);
-
-        if (!distPath) {
-            console.log(chalk.red('No existing dist/ directory found.'));
-            console.log(chalk.gray('Run without --skip-build to build the project.'));
-            return;
-        }
-
-        console.log(chalk.yellow(`Using existing dist: ${distPath}`));
-
-        // Validate the existing build
-        const validation = validateIrisBuild(distPath);
-        if (!validation.valid) {
-            console.log(chalk.red(formatValidationError(distPath, validation.errors)));
-            return;
-        }
-
-        console.log(chalk.green('\u2713 Existing build is valid'));
-    } else {
-        // Build the project
-        console.log(chalk.blue('Building project...'));
-        console.log();
-
-        const buildResult = await buildVueProject(projectPath, { silent: false });
-
-        if (!buildResult.success) {
-            console.log();
-            console.log(chalk.red(formatBuildError(projectPath, buildResult.error)));
-            return;
-        }
-
-        distPath = buildResult.distPath;
-        console.log();
-        console.log(chalk.green(`\u2713 Build completed successfully`));
-        console.log(chalk.gray(`  Output: ${distPath}`));
-
-        // Display any build warnings
-        displayWarnings(buildResult.warnings);
-
-        // Validate build output
-        const validation = validateIrisBuild(distPath);
-        if (!validation.valid) {
-            console.log();
-            console.log(chalk.red(formatValidationError(distPath, validation.errors)));
-            return;
-        }
-
-        console.log(chalk.green('\u2713 Build output validated'));
-    }
-
-    // Stage to CLI project (current workspace)
-    console.log();
-    console.log(chalk.blue('Staging to CLI workspace...'));
-
-    const stageResult = stageToWorkspace(distPath, slug, process.cwd());
-
-    if (!stageResult.success) {
-        console.log(chalk.red(`Failed to stage: ${stageResult.error}`));
-        return;
-    }
-
-    console.log(chalk.green(`\u2713 Staged ${stageResult.fileCount} files to ${stageResult.stagedPath}`));
-
-    // Display any staging warnings
-    displayWarnings(stageResult.warnings);
-
-    // Summary
-    console.log();
-    console.log(chalk.green('─'.repeat(48)));
-    console.log(chalk.green.bold('\u2713 Build & Stage Complete!'));
-    console.log();
-    console.log(chalk.gray(`Staged to: ${EXPORT_ROOT}/${IRIS_APPS_DIR}/${slug}/`));
-    console.log();
-
-    // Check if autopublish is running
-    if (isAutopublishRunning()) {
-        console.log(chalk.cyan('✓ Autopublish is running - changes will be deployed automatically'));
-    } else {
-        // Prompt to run publish now
-        const shouldPublish = await confirm({
-            message: 'Do you want to publish to Magentrix now?',
-            default: true
-        });
-
-        if (shouldPublish) {
-            console.log();
-            console.log(chalk.blue('Running publish...'));
-            console.log();
-
-            try {
-                await runPublish();
-            } catch (error) {
-                console.log(chalk.red(`\nPublish failed: ${error.message}`));
-                console.log(chalk.gray('You can run it manually later with:'), chalk.yellow('magentrix publish'));
-            }
-        } else {
-            console.log();
-            console.log(chalk.cyan('Next steps:'));
-            console.log(chalk.white(`  • Run ${chalk.yellow('magentrix publish')} to deploy to Magentrix`));
-            console.log(chalk.white(`  • Or use ${chalk.yellow('magentrix autopublish')} for automatic deployment`));
-        }
-    }
-};
-
-/**
- * Build and stage when running from inside a Vue project.
- * Prompts user to select which workspace to stage into.
- */
-async function buildFromVueProject(options) {
-    const { skipBuild, workspace: workspaceOption } = options;
-
-    // Use current directory as Vue project
-    const projectPath = process.cwd();
-    const vueConfig = readVueConfig(projectPath);
-
-    // Validate Vue config
-    if (!vueConfig.found) {
-        console.log(chalk.red(formatMissingConfigError(projectPath)));
-        return;
-    }
-
-    if (vueConfig.errors.length > 0) {
-        console.log(chalk.red(formatConfigErrors(vueConfig)));
-        return;
-    }
-
-    const { slug, appName } = vueConfig;
-
-    console.log(chalk.blue('\nVue Build & Stage'));
-    console.log(chalk.gray('─'.repeat(48)));
-    console.log(chalk.white(`  Project: ${chalk.cyan(appName)} (${slug})`));
-    console.log(chalk.white(`  Path: ${chalk.gray(projectPath)}`));
-    console.log();
-
-    // Determine which workspace to stage into
-    let workspacePath = workspaceOption;
-
-    if (workspacePath) {
-        workspacePath = resolve(workspacePath);
-        if (!existsSync(workspacePath)) {
-            console.log(chalk.red(`Error: Workspace path does not exist: ${workspacePath}`));
-            return;
-        }
-    } else {
-        // Prompt user to select a workspace
-        const result = await selectWorkspace();
-        if (!result) return; // User cancelled
-        workspacePath = result;
-    }
-
-    // Ensure project is linked
-    const linked = findLinkedProjectByPath(projectPath);
-    if (!linked) {
-        const shouldLink = await confirm({
-            message: 'This project is not linked. Link it now?',
-            default: true
-        });
-
-        if (shouldLink) {
-            const linkResult = linkVueProject(projectPath);
-            if (!linkResult.success) {
-                console.log(chalk.red(`Failed to link project: ${linkResult.error}`));
-                return;
-            }
-            console.log(chalk.green(`\u2713 Project linked`));
-        }
-    }
-
-    let distPath;
-
-    if (skipBuild) {
-        // Use existing dist
-        distPath = findDistDirectory(projectPath);
-
-        if (!distPath) {
-            console.log(chalk.red('No existing dist/ directory found.'));
-            console.log(chalk.gray('Run without --skip-build to build the project.'));
-            return;
-        }
-
-        console.log(chalk.yellow(`Using existing dist: ${distPath}`));
-
-        // Validate the existing build
-        const validation = validateIrisBuild(distPath);
-        if (!validation.valid) {
-            console.log(chalk.red(formatValidationError(distPath, validation.errors)));
-            return;
-        }
-
-        console.log(chalk.green('\u2713 Existing build is valid'));
-    } else {
-        // Build the project
-        console.log(chalk.blue('Building project...'));
-        console.log();
-
-        const buildResult = await buildVueProject(projectPath, { silent: false });
-
-        if (!buildResult.success) {
-            console.log();
-            console.log(chalk.red(formatBuildError(projectPath, buildResult.error)));
-            return;
-        }
-
-        distPath = buildResult.distPath;
-        console.log();
-        console.log(chalk.green(`\u2713 Build completed successfully`));
-        console.log(chalk.gray(`  Output: ${distPath}`));
-
-        // Display any build warnings
-        displayWarnings(buildResult.warnings);
-
-        // Validate build output
-        const validation = validateIrisBuild(distPath);
-        if (!validation.valid) {
-            console.log();
-            console.log(chalk.red(formatValidationError(distPath, validation.errors)));
-            return;
-        }
-
-        console.log(chalk.green('\u2713 Build output validated'));
-    }
-
-    // Check if workspace might be out of sync and offer to pull first (BEFORE staging)
-    // This ensures pull doesn't overwrite our staged files
-    console.log();
-    console.log(chalk.gray('Checking workspace sync status...'));
-
-    // Check for a previous incomplete pull first — `magentrix status` only checks
-    // code entities, so a partial pull that synced code but not assets would falsely
-    // report "in sync". The marker file catches this case.
-    const workspaceConfig = new Config({ projectDir: workspacePath });
-    const hadIncompletePull = workspaceConfig.read('pullIncomplete', { global: false, filename: 'config.json' });
-
-    const syncStatus = await checkWorkspaceSyncStatus(workspacePath);
-    const needsPull = syncStatus.needsPull || !!hadIncompletePull;
-
-    if (needsPull) {
-        console.log();
-        if (hadIncompletePull && !syncStatus.needsPull) {
-            console.log(chalk.yellow('⚠ A previous pull did not complete. Your workspace may be out of sync.'));
-        } else {
-            console.log(chalk.yellow('⚠ Your workspace may be out of sync with the server.'));
-        }
-
-        const shouldPull = await confirm({
-            message: 'Would you like to pull latest changes first?',
-            default: true
-        });
-
-        if (shouldPull) {
-            console.log();
-            console.log(chalk.blue('Running pull from workspace...'));
-            console.log();
-
-            // Mark pull as in-progress before starting
-            workspaceConfig.save('pullIncomplete', true, { global: false, filename: 'config.json' });
-
-            const pullSuccess = await runCommandFromWorkspace(workspacePath, 'pull');
-
-            if (pullSuccess) {
-                // Pull completed successfully — clear the marker
-                workspaceConfig.removeKey('pullIncomplete', { filename: 'config.json' });
-            } else {
-                // Pull failed or was cancelled — marker stays for next run
-                console.log();
-                console.log(chalk.yellow('Pull encountered issues. You may want to resolve them manually.'));
-
-                const continueAnyway = await confirm({
-                    message: 'Do you still want to continue with staging and publishing?',
-                    default: false
-                });
-
-                if (!continueAnyway) {
-                    console.log();
-                    console.log(chalk.cyan('To continue manually:'));
-                    console.log(chalk.white(`  1. Navigate to workspace: ${chalk.yellow(`cd "${workspacePath}"`)}`));
-                    console.log(chalk.white(`  2. Run ${chalk.yellow('magentrix pull')} to resolve conflicts`));
-                    console.log(chalk.white(`  3. Run ${chalk.yellow('magentrix vue-run-build --skip-build')} to stage`));
-                    console.log(chalk.white(`  4. Run ${chalk.yellow('magentrix publish')} to deploy`));
-                    return;
-                }
-            }
-            console.log();
-        } else {
-            // User declined to pull - block publishing from out-of-sync workspace
-            console.log();
-            console.log(chalk.red('Publishing Iris apps from an out-of-sync workspace is not allowed.'));
-            console.log(chalk.gray('This prevents conflicts and ensures your deployment is based on the latest server state.'));
-            console.log();
-            console.log(chalk.cyan('To continue:'));
-            console.log(chalk.white(`  1. Navigate to workspace: ${chalk.yellow(`cd "${workspacePath}"`)}`));
-            console.log(chalk.white(`  2. Run ${chalk.yellow('magentrix pull')} to sync with server`));
-            console.log(chalk.white(`  3. Run ${chalk.yellow('magentrix publish')} to deploy`));
-            return;
-        }
-    } else if (syncStatus.checked) {
-        console.log(chalk.green('✓ Workspace is in sync'));
-    }
-
-    // Stage to selected workspace (AFTER pull to avoid overwriting)
-    console.log();
-    console.log(chalk.blue(`Staging to workspace: ${workspacePath}`));
-
-    const stageResult = stageToWorkspace(distPath, slug, workspacePath);
-
-    if (!stageResult.success) {
-        console.log(chalk.red(`Failed to stage: ${stageResult.error}`));
-        return;
-    }
-
-    console.log(chalk.green(`\u2713 Staged ${stageResult.fileCount} files to ${stageResult.stagedPath}`));
-
-    // Display any staging warnings
-    displayWarnings(stageResult.warnings);
-
-    // Summary
-    console.log();
-    console.log(chalk.green('─'.repeat(48)));
-    console.log(chalk.green.bold('\u2713 Build & Stage Complete!'));
-    console.log();
-    console.log(chalk.gray(`Staged to: ${stageResult.stagedPath}`));
-    console.log();
-
-    // Ask if they want to publish now
-    const shouldPublish = await confirm({
-        message: 'Do you want to publish to Magentrix now?',
-        default: true
-    });
-
-    if (shouldPublish) {
-        console.log();
-        console.log(chalk.blue('Running publish from workspace...'));
-        console.log();
-
-        const publishSuccess = await runCommandFromWorkspace(workspacePath, 'publish');
-
-        if (!publishSuccess) {
-            console.log();
-            console.log(chalk.cyan('To publish manually:'));
-            console.log(chalk.white(`  1. Navigate to workspace: ${chalk.yellow(`cd "${workspacePath}"`)}`));
-            console.log(chalk.white(`  2. Run ${chalk.yellow('magentrix publish')}`));
-        }
-    } else {
-        console.log();
-        console.log(chalk.cyan('Next steps:'));
-        console.log(chalk.white(`  1. Navigate to workspace: ${chalk.yellow(`cd "${workspacePath}"`)}`));
-        console.log(chalk.white(`  2. Run ${chalk.yellow('magentrix publish')} to deploy to Magentrix`));
-        console.log(chalk.white(`     Or use ${chalk.yellow('magentrix autopublish')} for automatic deployment`));
-    }
-}
-
-/**
- * Check if a workspace needs to pull (has remote changes or conflicts).
- *
- * @param {string} workspacePath - Path to the Magentrix workspace
- * @returns {Promise<{checked: boolean, needsPull: boolean, timedOut: boolean}>}
- */
-async function checkWorkspaceSyncStatus(workspacePath) {
-    return new Promise((resolvePromise) => {
-        const isWindows = process.platform === 'win32';
-        const npmCmd = isWindows ? 'npx.cmd' : 'npx';
-
-        let output = '';
-        let resolved = false;
-
-        const child = spawn(npmCmd, ['magentrix', 'status'], {
-            cwd: workspacePath,
-            stdio: ['inherit', 'pipe', 'pipe'],
-            shell: isWindows
-        });
-
-        // Set timeout for status check
-        const timeout = setTimeout(() => {
-            if (!resolved) {
-                resolved = true;
-                try {
-                    child.kill('SIGTERM');
-                } catch {
-                    // Ignore kill errors
-                }
-                console.log(chalk.yellow(`\n⚠ Status check timed out after ${STATUS_CHECK_TIMEOUT / 1000} seconds`));
-                resolvePromise({ checked: false, needsPull: false, timedOut: true });
-            }
-        }, STATUS_CHECK_TIMEOUT);
-
-        child.stdout.on('data', (data) => {
-            output += data.toString();
-        });
-
-        child.stderr.on('data', (data) => {
-            output += data.toString();
-        });
-
-        child.on('close', (code) => {
-            if (resolved) return;
-            resolved = true;
-            clearTimeout(timeout);
-
-            // Check output for specific issue indicators from status command
-            // Note: We avoid checking for "remote" as it appears in normal output
-            // ("Checking local files vs remote Magentrix...")
-            const lowerOutput = output.toLowerCase();
-
-            // If everything is in sync, this message appears
-            const isInSync = lowerOutput.includes('all files are up to date') ||
-                             lowerOutput.includes('in sync');
-
-            // Check for specific issue keywords from logFileStatus output
-            const hasConflict = lowerOutput.includes('conflict');
-            const isOutdated = lowerOutput.includes('outdated');
-            const isAhead = lowerOutput.includes('is ahead');
-            const isMissing = lowerOutput.includes('is missing');
-            const hasContentMismatch = lowerOutput.includes('content mismatch');
-            const hasWarnings = lowerOutput.includes('⚠️') || lowerOutput.includes('🛑');
-
-            const needsPull = !isInSync && (hasConflict || isOutdated || isAhead || isMissing || hasContentMismatch || hasWarnings);
-
-            resolvePromise({ checked: code === 0, needsPull, timedOut: false });
-        });
-
-        child.on('error', (err) => {
-            if (resolved) return;
-            resolved = true;
-            clearTimeout(timeout);
-
-            // If we can't check, assume it's fine and let them proceed
-            console.log(chalk.yellow(`\n⚠ Could not check sync status: ${err.message}`));
-            resolvePromise({ checked: false, needsPull: false, timedOut: false });
-        });
-    });
-}
-
-/**
- * Run a magentrix command from a specific workspace directory.
- *
- * @param {string} workspacePath - Path to the Magentrix workspace
- * @param {string} command - The magentrix command to run (e.g., 'pull', 'publish')
- * @param {number} timeout - Optional timeout in milliseconds (defaults to COMMAND_TIMEOUT)
- * @returns {Promise<boolean>} - True if command succeeded
- */
-async function runCommandFromWorkspace(workspacePath, command, timeout = COMMAND_TIMEOUT) {
-    return new Promise((resolvePromise) => {
-        const isWindows = process.platform === 'win32';
-        const npmCmd = isWindows ? 'npx.cmd' : 'npx';
-
-        let resolved = false;
-
-        const child = spawn(npmCmd, ['magentrix', command], {
-            cwd: workspacePath,
-            stdio: 'inherit',
-            shell: isWindows
-        });
-
-        // Set timeout for command execution
-        const timeoutId = setTimeout(() => {
-            if (!resolved) {
-                resolved = true;
-                try {
-                    child.kill('SIGTERM');
-                } catch {
-                    // Ignore kill errors
-                }
-                console.log();
-                console.log(chalk.red(formatTimeoutError({
-                    operation: `magentrix ${command}`,
-                    timeout: timeout,
-                    suggestion: `The ${command} operation is taking too long. Check your network connection or try again later.`
-                })));
-                resolvePromise(false);
-            }
-        }, timeout);
-
-        child.on('close', (code) => {
-            if (resolved) return;
-            resolved = true;
-            clearTimeout(timeoutId);
-            resolvePromise(code === 0);
-        });
-
-        child.on('error', (err) => {
-            if (resolved) return;
-            resolved = true;
-            clearTimeout(timeoutId);
-            console.log(chalk.yellow(`Warning: Could not run ${command}: ${err.message}`));
-            resolvePromise(false);
-        });
-    });
-}
-
-/**
- * Prompt user to select a Magentrix workspace.
- *
- * @returns {Promise<string | null>} - Selected workspace path or null if cancelled
- */
-async function selectWorkspace() {
-    const workspaces = getValidWorkspaces();
-
-    if (workspaces.length === 0) {
-        console.log(chalk.yellow('No Magentrix workspaces found.'));
-        console.log();
-        console.log(chalk.gray('To register a workspace:'));
-        console.log(chalk.white(`  • Run ${chalk.cyan('magentrix')} from an existing workspace (auto-registers it)`));
-        console.log(chalk.white(`  • Or run ${chalk.cyan('magentrix setup')} in a new directory to create one`));
-        console.log();
-        console.log(chalk.gray('Or specify a workspace path directly:'));
-        console.log(chalk.white(`  ${chalk.cyan('magentrix vue-run-build --workspace /path/to/workspace')}`));
-        console.log();
-
-        // Allow manual entry
-        const manualPath = await input({
-            message: 'Enter the path to your Magentrix workspace (or leave empty to cancel):',
-            validate: (value) => {
-                if (!value.trim()) return true; // Allow empty for cancel
-                const resolved = resolve(value);
-                if (!existsSync(resolved)) {
-                    return `Path does not exist: ${resolved}`;
-                }
-                const magentrixFolder = join(resolved, '.magentrix');
-                if (!existsSync(magentrixFolder)) {
-                    return `Not a Magentrix workspace (missing .magentrix folder): ${resolved}`;
-                }
-                return true;
-            }
-        });
-
-        if (!manualPath.trim()) {
-            console.log(chalk.gray('Cancelled.'));
-            return null;
-        }
-
-        return resolve(manualPath);
-    }
-
-    // Build choices from registered workspaces
-    const choices = workspaces.map(w => ({
-        name: `${w.path}`,
-        value: w.path,
-        description: chalk.dim(`→ ${w.instanceUrl}`)
-    }));
-
-    choices.push({
-        name: 'Enter path manually',
-        value: '__manual__',
-        description: chalk.dim('→ Specify the full path to a workspace')
-    });
-
-    choices.push({
-        name: 'Cancel',
-        value: '__cancel__'
-    });
-
-    const choice = await select({
-        message: 'Which workspace do you want to stage into?',
-        choices
-    });
-
-    if (choice === '__cancel__') {
-        console.log(chalk.gray('Cancelled.'));
-        return null;
-    }
-
-    if (choice === '__manual__') {
-        const manualPath = await input({
-            message: 'Enter the path to your Magentrix workspace:',
-            validate: (value) => {
-                if (!value.trim()) {
-                    return 'Path is required';
-                }
-                const resolved = resolve(value);
-                if (!existsSync(resolved)) {
-                    return `Path does not exist: ${resolved}`;
-                }
-                const magentrixFolder = join(resolved, '.magentrix');
-                if (!existsSync(magentrixFolder)) {
-                    return `Not a Magentrix workspace (missing .magentrix folder): ${resolved}`;
-                }
-                return true;
-            }
-        });
-
-        return resolve(manualPath);
-    }
-
-    return choice;
-}
-
-/**
- * Prompt user to select a project.
- *
- * @returns {Promise<{path: string, config: object} | null>}
- */
-async function selectProject() {
-    const projectsWithStatus = getLinkedProjectsWithStatus();
-
-    // Check if CWD is a Vue project (and not already linked)
-    const cwdConfig = readVueConfig(process.cwd());
-    const inVueProject = cwdConfig.found && cwdConfig.errors.length === 0;
-    const cwdAlreadyLinked = projectsWithStatus.some(p =>
-        resolve(p.path) === resolve(process.cwd())
-    );
-
-    // Build choices using the helper
-    const choices = buildProjectChoices({
-        includeManual: true,
-        includeCancel: true,
-        showInvalid: true
-    });
-
-    // If CWD is a valid Vue project and not linked, add it at the top
-    if (inVueProject && !cwdAlreadyLinked) {
-        choices.unshift({
-            name: `${cwdConfig.appName} (${cwdConfig.slug}) - Current directory (not linked)`,
-            value: { type: 'cwd', path: process.cwd() }
-        });
-    }
-
-    // Check if we have any projects to show
-    const hasProjects = choices.some(c => c.value?.type === 'linked' || c.value?.type === 'cwd');
-
-    if (!hasProjects) {
-        console.log(chalk.yellow('No linked Vue projects found.'));
-        console.log();
-        console.log(chalk.gray('To get started:'));
-        console.log(chalk.white(`  1. Link a Vue project: ${chalk.cyan('magentrix iris-app-link')}`));
-        console.log(chalk.white(`  2. Or specify path: ${chalk.cyan('magentrix vue-run-build --path /path/to/vue-project')}`));
-        console.log();
-    }
-
-    const choice = await select({
-        message: 'Which project do you want to build?',
-        choices
-    });
-
-    if (choice.type === 'cancel') {
-        console.log(chalk.gray('Cancelled.'));
-        return null;
-    }
-
-    if (choice.type === 'manual') {
-        const manualPath = await input({
-            message: 'Enter the path to your Vue project:',
-            validate: (value) => {
-                if (!value.trim()) {
-                    return 'Path is required';
-                }
-                const resolved = resolve(value);
-                if (!existsSync(resolved)) {
-                    return `Path does not exist: ${resolved}`;
-                }
-                return true;
-            }
-        });
-
-        const config = readVueConfig(resolve(manualPath));
-        return { path: resolve(manualPath), config };
-    }
-
-    // Linked project or CWD
-    const config = readVueConfig(choice.path);
-    return { path: choice.path, config };
-}
-
-export default vueBuildStage;
+import chalk from 'chalk';
+import { select, input, confirm } from '@inquirer/prompts';
+import { existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { spawn } from 'node:child_process';
+import Config from '../../utils/config.js';
+import { runPublish } from '../publish.js';
+import { isAutopublishRunning } from '../../utils/autopublishLock.js';
+import {
+    buildVueProject,
+    stageToWorkspace,
+    findDistDirectory,
+    formatBuildError,
+    formatValidationError
+} from '../../utils/iris/builder.js';
+import { validateIrisBuild } from '../../utils/iris/validator.js';
+import {
+    readVueConfig,
+    formatMissingConfigError,
+    formatConfigErrors
+} from '../../utils/iris/config-reader.js';
+import {
+    getLinkedProjectsWithStatus,
+    linkVueProject,
+    findLinkedProjectByPath,
+    buildProjectChoices
+} from '../../utils/iris/linker.js';
+import { EXPORT_ROOT, IRIS_APPS_DIR, HASHED_CWD } from '../../vars/global.js';
+import { getValidWorkspaces } from '../../utils/workspaces.js';
+import { formatTimeoutError } from '../../utils/iris/errors.js';
+
+const config = new Config();
+
+/**
+ * Timeout for status check operations (30 seconds).
+ */
+const STATUS_CHECK_TIMEOUT = 30000;
+
+/**
+ * Timeout for command execution (5 minutes).
+ */
+const COMMAND_TIMEOUT = 5 * 60 * 1000;
+
+/**
+ * Display warnings from build/stage operations.
+ *
+ * @param {string[]} warnings - Array of warning messages
+ */
+function displayWarnings(warnings) {
+    if (!warnings || warnings.length === 0) return;
+
+    for (const warning of warnings) {
+        console.log(chalk.yellow(`⚠ ${warning}`));
+    }
+}
+
+/**
+ * Check if the current directory is a Vue project (has config.ts).
+ * @returns {boolean}
+ */
+function isInVueProject() {
+    const configLocations = [
+        'src/config.ts',
+        'config.ts',
+        'src/iris-config.ts',
+        'iris-config.ts'
+    ];
+    return configLocations.some(loc => existsSync(join(process.cwd(), loc)));
+}
+
+/**
+ * Check if the current directory appears to be a Magentrix workspace.
+ * @returns {boolean} - True if in a Magentrix workspace
+ */
+function isMagentrixWorkspace() {
+    const magentrixFolder = join(process.cwd(), '.magentrix');
+    const srcFolder = join(process.cwd(), 'src');
+
+    // Check for .magentrix folder
+    if (!existsSync(magentrixFolder)) return false;
+
+    // Check for src folder (typical workspace structure)
+    if (!existsSync(srcFolder)) return false;
+
+    // Check if credentials are configured (instanceUrl or apiKey in global config)
+    const instanceUrl = config.read('instanceUrl', { global: true, pathHash: HASHED_CWD });
+    const apiKey = config.read('apiKey', { global: true, pathHash: HASHED_CWD });
+
+    return !!(instanceUrl || apiKey);
+}
+
+/**
+ * vue-run-build command - Build a Vue project and stage to CLI workspace.
+ *
+ * Two modes of operation:
+ * 1. Run from Magentrix workspace: prompts for which Vue project to build
+ * 2. Run from Vue project: prompts for which workspace to stage into
+ *
+ * Options:
+ *   --path <dir>        Specify Vue project path directly
+ *   --skip-build        Use existing dist/ without rebuilding
+ *   --workspace <dir>   Specify Magentrix workspace path directly
+ */
+export const vueBuildStage = async (options = {}) => {
+    process.stdout.write('\x1Bc'); // Clear console
+
+    const { path: pathOption, skipBuild, workspace: workspaceOption } = options;
+
+    // Detect which mode we're in
+    const inVueProject = isInVueProject();
+    const inWorkspace = isMagentrixWorkspace();
+
+    // If run from a Vue project, use reversed logic
+    if (inVueProject && !inWorkspace) {
+        await buildFromVueProject(options);
+        return;
+    }
+
+    // Standard mode: run from workspace, select Vue project
+    // Warn if not in a Magentrix workspace
+    if (!inWorkspace) {
+        console.log(chalk.yellow('⚠ Warning: Magentrix Workspace Not Detected'));
+        console.log(chalk.gray('─'.repeat(48)));
+        console.log(chalk.white('\nThis command should be run from your Magentrix CLI workspace directory.'));
+        console.log(chalk.white('It stages Vue.js build files to ') + chalk.cyan('src/iris-apps/<slug>/'));
+        console.log();
+        console.log(chalk.white('Expected workspace indicators:'));
+        console.log(chalk.gray('  • .magentrix/ folder (config and cache)'));
+        console.log(chalk.gray('  • src/ folder (code files and assets)'));
+        console.log(chalk.gray('  • Magentrix credentials configured'));
+        console.log();
+        console.log(chalk.white('Current directory: ') + chalk.gray(process.cwd()));
+        console.log();
+
+        const shouldContinue = await confirm({
+            message: 'Do you want to continue anyway?',
+            default: false
+        });
+
+        if (!shouldContinue) {
+            console.log(chalk.gray('\nCancelled. Run this command from your Magentrix workspace.'));
+            return;
+        }
+
+        console.log();
+    }
+
+    // Determine which project to build
+    let projectPath = pathOption;
+    let vueConfig = null;
+
+    if (projectPath) {
+        // Path provided via option
+        projectPath = resolve(projectPath);
+
+        if (!existsSync(projectPath)) {
+            console.log(chalk.red(`Error: Path does not exist: ${projectPath}`));
+            return;
+        }
+
+        vueConfig = readVueConfig(projectPath);
+    } else {
+        // Prompt user to select a project
+        const result = await selectProject();
+        if (!result) return; // User cancelled
+
+        projectPath = result.path;
+        vueConfig = result.config;
+    }
+
+    // Validate Vue config
+    if (!vueConfig.found) {
+        console.log(chalk.red(formatMissingConfigError(projectPath)));
+        return;
+    }
+
+    if (vueConfig.errors.length > 0) {
+        console.log(chalk.red(formatConfigErrors(vueConfig)));
+        return;
+    }
+
+    const { slug, appName } = vueConfig;
+
+    console.log(chalk.blue('\nVue Build & Stage'));
+    console.log(chalk.gray('─'.repeat(48)));
+    console.log(chalk.white(`  Project: ${chalk.cyan(appName)} (${slug})`));
+    console.log(chalk.white(`  Path: ${chalk.gray(projectPath)}`));
+    console.log();
+
+    // Ensure project is linked
+    const linked = findLinkedProjectByPath(projectPath);
+    if (!linked) {
+        const shouldLink = await confirm({
+            message: 'This project is not linked. Link it now?',
+            default: true
+        });
+
+        if (shouldLink) {
+            const linkResult = linkVueProject(projectPath);
+            if (!linkResult.success) {
+                console.log(chalk.red(`Failed to link project: ${linkResult.error}`));
+                return;
+            }
+            console.log(chalk.green(`\u2713 Project linked`));
+        }
+    }
+
+    let distPath;
+
+    if (skipBuild) {
+        // Use existing dist
+        distPath = findDistDirectory(projectPath);
+
+        if (!distPath) {
+            console.log(chalk.red('No existing dist/ directory found.'));
+            console.log(chalk.gray('Run without --skip-build to build the project.'));
+            return;
+        }
+
+        console.log(chalk.yellow(`Using existing dist: ${distPath}`));
+
+        // Validate the existing build
+        const validation = validateIrisBuild(distPath);
+        if (!validation.valid) {
+            console.log(chalk.red(formatValidationError(distPath, validation.errors)));
+            return;
+        }
+
+        console.log(chalk.green('\u2713 Existing build is valid'));
+    } else {
+        // Build the project
+        console.log(chalk.blue('Building project...'));
+        console.log();
+
+        const buildResult = await buildVueProject(projectPath, { silent: false });
+
+        if (!buildResult.success) {
+            console.log();
+            console.log(chalk.red(formatBuildError(projectPath, buildResult.error)));
+            return;
+        }
+
+        distPath = buildResult.distPath;
+        console.log();
+        console.log(chalk.green(`\u2713 Build completed successfully`));
+        console.log(chalk.gray(`  Output: ${distPath}`));
+
+        // Display any build warnings
+        displayWarnings(buildResult.warnings);
+
+        // Validate build output
+        const validation = validateIrisBuild(distPath);
+        if (!validation.valid) {
+            console.log();
+            console.log(chalk.red(formatValidationError(distPath, validation.errors)));
+            return;
+        }
+
+        console.log(chalk.green('\u2713 Build output validated'));
+    }
+
+    // Stage to CLI project (current workspace)
+    console.log();
+    console.log(chalk.blue('Staging to CLI workspace...'));
+
+    const stageResult = stageToWorkspace(distPath, slug, process.cwd());
+
+    if (!stageResult.success) {
+        console.log(chalk.red(`Failed to stage: ${stageResult.error}`));
+        return;
+    }
+
+    console.log(chalk.green(`\u2713 Staged ${stageResult.fileCount} files to ${stageResult.stagedPath}`));
+
+    // Display any staging warnings
+    displayWarnings(stageResult.warnings);
+
+    // Summary
+    console.log();
+    console.log(chalk.green('─'.repeat(48)));
+    console.log(chalk.green.bold('\u2713 Build & Stage Complete!'));
+    console.log();
+    console.log(chalk.gray(`Staged to: ${EXPORT_ROOT}/${IRIS_APPS_DIR}/${slug}/`));
+    console.log();
+
+    // Check if autopublish is running
+    if (isAutopublishRunning()) {
+        console.log(chalk.cyan('✓ Autopublish is running - changes will be deployed automatically'));
+    } else {
+        // Prompt to run publish now
+        const shouldPublish = await confirm({
+            message: 'Do you want to publish to Magentrix now?',
+            default: true
+        });
+
+        if (shouldPublish) {
+            console.log();
+            console.log(chalk.blue('Running publish...'));
+            console.log();
+
+            try {
+                await runPublish();
+            } catch (error) {
+                console.log(chalk.red(`\nPublish failed: ${error.message}`));
+                console.log(chalk.gray('You can run it manually later with:'), chalk.yellow('magentrix publish'));
+            }
+        } else {
+            console.log();
+            console.log(chalk.cyan('Next steps:'));
+            console.log(chalk.white(`  • Run ${chalk.yellow('magentrix publish')} to deploy to Magentrix`));
+            console.log(chalk.white(`  • Or use ${chalk.yellow('magentrix autopublish')} for automatic deployment`));
+        }
+    }
+};
+
+/**
+ * Build and stage when running from inside a Vue project.
+ * Prompts user to select which workspace to stage into.
+ */
+async function buildFromVueProject(options) {
+    const { skipBuild, workspace: workspaceOption } = options;
+
+    // Use current directory as Vue project
+    const projectPath = process.cwd();
+    const vueConfig = readVueConfig(projectPath);
+
+    // Validate Vue config
+    if (!vueConfig.found) {
+        console.log(chalk.red(formatMissingConfigError(projectPath)));
+        return;
+    }
+
+    if (vueConfig.errors.length > 0) {
+        console.log(chalk.red(formatConfigErrors(vueConfig)));
+        return;
+    }
+
+    const { slug, appName } = vueConfig;
+
+    console.log(chalk.blue('\nVue Build & Stage'));
+    console.log(chalk.gray('─'.repeat(48)));
+    console.log(chalk.white(`  Project: ${chalk.cyan(appName)} (${slug})`));
+    console.log(chalk.white(`  Path: ${chalk.gray(projectPath)}`));
+    console.log();
+
+    // Determine which workspace to stage into
+    let workspacePath = workspaceOption;
+
+    if (workspacePath) {
+        workspacePath = resolve(workspacePath);
+        if (!existsSync(workspacePath)) {
+            console.log(chalk.red(`Error: Workspace path does not exist: ${workspacePath}`));
+            return;
+        }
+    } else {
+        // Prompt user to select a workspace
+        const result = await selectWorkspace();
+        if (!result) return; // User cancelled
+        workspacePath = result;
+    }
+
+    // Ensure project is linked
+    const linked = findLinkedProjectByPath(projectPath);
+    if (!linked) {
+        const shouldLink = await confirm({
+            message: 'This project is not linked. Link it now?',
+            default: true
+        });
+
+        if (shouldLink) {
+            const linkResult = linkVueProject(projectPath);
+            if (!linkResult.success) {
+                console.log(chalk.red(`Failed to link project: ${linkResult.error}`));
+                return;
+            }
+            console.log(chalk.green(`\u2713 Project linked`));
+        }
+    }
+
+    let distPath;
+
+    if (skipBuild) {
+        // Use existing dist
+        distPath = findDistDirectory(projectPath);
+
+        if (!distPath) {
+            console.log(chalk.red('No existing dist/ directory found.'));
+            console.log(chalk.gray('Run without --skip-build to build the project.'));
+            return;
+        }
+
+        console.log(chalk.yellow(`Using existing dist: ${distPath}`));
+
+        // Validate the existing build
+        const validation = validateIrisBuild(distPath);
+        if (!validation.valid) {
+            console.log(chalk.red(formatValidationError(distPath, validation.errors)));
+            return;
+        }
+
+        console.log(chalk.green('\u2713 Existing build is valid'));
+    } else {
+        // Build the project
+        console.log(chalk.blue('Building project...'));
+        console.log();
+
+        const buildResult = await buildVueProject(projectPath, { silent: false });
+
+        if (!buildResult.success) {
+            console.log();
+            console.log(chalk.red(formatBuildError(projectPath, buildResult.error)));
+            return;
+        }
+
+        distPath = buildResult.distPath;
+        console.log();
+        console.log(chalk.green(`\u2713 Build completed successfully`));
+        console.log(chalk.gray(`  Output: ${distPath}`));
+
+        // Display any build warnings
+        displayWarnings(buildResult.warnings);
+
+        // Validate build output
+        const validation = validateIrisBuild(distPath);
+        if (!validation.valid) {
+            console.log();
+            console.log(chalk.red(formatValidationError(distPath, validation.errors)));
+            return;
+        }
+
+        console.log(chalk.green('\u2713 Build output validated'));
+    }
+
+    // Check if workspace might be out of sync and offer to pull first (BEFORE staging)
+    // This ensures pull doesn't overwrite our staged files
+    console.log();
+    console.log(chalk.gray('Checking workspace sync status...'));
+
+    // Check for a previous incomplete pull first — `magentrix status` only checks
+    // code entities, so a partial pull that synced code but not assets would falsely
+    // report "in sync". The marker file catches this case.
+    const workspaceConfig = new Config({ projectDir: workspacePath });
+    const hadIncompletePull = workspaceConfig.read('pullIncomplete', { global: false, filename: 'config.json' });
+
+    const syncStatus = await checkWorkspaceSyncStatus(workspacePath);
+    const needsPull = syncStatus.needsPull || !!hadIncompletePull;
+
+    if (needsPull) {
+        console.log();
+        if (hadIncompletePull && !syncStatus.needsPull) {
+            console.log(chalk.yellow('⚠ A previous pull did not complete. Your workspace may be out of sync.'));
+        } else {
+            console.log(chalk.yellow('⚠ Your workspace may be out of sync with the server.'));
+        }
+
+        const shouldPull = await confirm({
+            message: 'Would you like to pull latest changes first?',
+            default: true
+        });
+
+        if (shouldPull) {
+            console.log();
+            console.log(chalk.blue('Running pull from workspace...'));
+            console.log();
+
+            // Mark pull as in-progress before starting
+            workspaceConfig.save('pullIncomplete', true, { global: false, filename: 'config.json' });
+
+            const pullSuccess = await runCommandFromWorkspace(workspacePath, 'pull');
+
+            if (pullSuccess) {
+                // Pull completed successfully — clear the marker
+                workspaceConfig.removeKey('pullIncomplete', { filename: 'config.json' });
+            } else {
+                // Pull failed or was cancelled — marker stays for next run
+                console.log();
+                console.log(chalk.yellow('Pull encountered issues. You may want to resolve them manually.'));
+
+                const continueAnyway = await confirm({
+                    message: 'Do you still want to continue with staging and publishing?',
+                    default: false
+                });
+
+                if (!continueAnyway) {
+                    console.log();
+                    console.log(chalk.cyan('To continue manually:'));
+                    console.log(chalk.white(`  1. Navigate to workspace: ${chalk.yellow(`cd "${workspacePath}"`)}`));
+                    console.log(chalk.white(`  2. Run ${chalk.yellow('magentrix pull')} to resolve conflicts`));
+                    console.log(chalk.white(`  3. Run ${chalk.yellow('magentrix vue-run-build --skip-build')} to stage`));
+                    console.log(chalk.white(`  4. Run ${chalk.yellow('magentrix publish')} to deploy`));
+                    return;
+                }
+            }
+            console.log();
+        } else {
+            // User declined to pull - block publishing from out-of-sync workspace
+            console.log();
+            console.log(chalk.red('Publishing Iris apps from an out-of-sync workspace is not allowed.'));
+            console.log(chalk.gray('This prevents conflicts and ensures your deployment is based on the latest server state.'));
+            console.log();
+            console.log(chalk.cyan('To continue:'));
+            console.log(chalk.white(`  1. Navigate to workspace: ${chalk.yellow(`cd "${workspacePath}"`)}`));
+            console.log(chalk.white(`  2. Run ${chalk.yellow('magentrix pull')} to sync with server`));
+            console.log(chalk.white(`  3. Run ${chalk.yellow('magentrix publish')} to deploy`));
+            return;
+        }
+    } else if (syncStatus.checked) {
+        console.log(chalk.green('✓ Workspace is in sync'));
+    }
+
+    // Stage to selected workspace (AFTER pull to avoid overwriting)
+    console.log();
+    console.log(chalk.blue(`Staging to workspace: ${workspacePath}`));
+
+    const stageResult = stageToWorkspace(distPath, slug, workspacePath);
+
+    if (!stageResult.success) {
+        console.log(chalk.red(`Failed to stage: ${stageResult.error}`));
+        return;
+    }
+
+    console.log(chalk.green(`\u2713 Staged ${stageResult.fileCount} files to ${stageResult.stagedPath}`));
+
+    // Display any staging warnings
+    displayWarnings(stageResult.warnings);
+
+    // Summary
+    console.log();
+    console.log(chalk.green('─'.repeat(48)));
+    console.log(chalk.green.bold('\u2713 Build & Stage Complete!'));
+    console.log();
+    console.log(chalk.gray(`Staged to: ${stageResult.stagedPath}`));
+    console.log();
+
+    // Ask if they want to publish now
+    const shouldPublish = await confirm({
+        message: 'Do you want to publish to Magentrix now?',
+        default: true
+    });
+
+    if (shouldPublish) {
+        console.log();
+        console.log(chalk.blue('Running publish from workspace...'));
+        console.log();
+
+        const publishSuccess = await runCommandFromWorkspace(workspacePath, 'publish');
+
+        if (!publishSuccess) {
+            console.log();
+            console.log(chalk.cyan('To publish manually:'));
+            console.log(chalk.white(`  1. Navigate to workspace: ${chalk.yellow(`cd "${workspacePath}"`)}`));
+            console.log(chalk.white(`  2. Run ${chalk.yellow('magentrix publish')}`));
+        }
+    } else {
+        console.log();
+        console.log(chalk.cyan('Next steps:'));
+        console.log(chalk.white(`  1. Navigate to workspace: ${chalk.yellow(`cd "${workspacePath}"`)}`));
+        console.log(chalk.white(`  2. Run ${chalk.yellow('magentrix publish')} to deploy to Magentrix`));
+        console.log(chalk.white(`     Or use ${chalk.yellow('magentrix autopublish')} for automatic deployment`));
+    }
+}
+
+/**
+ * Check if a workspace needs to pull (has remote changes or conflicts).
+ *
+ * @param {string} workspacePath - Path to the Magentrix workspace
+ * @returns {Promise<{checked: boolean, needsPull: boolean, timedOut: boolean}>}
+ */
+async function checkWorkspaceSyncStatus(workspacePath) {
+    return new Promise((resolvePromise) => {
+        const isWindows = process.platform === 'win32';
+        const npmCmd = isWindows ? 'npx.cmd' : 'npx';
+
+        let output = '';
+        let resolved = false;
+
+        const child = spawn(npmCmd, ['magentrix', 'status'], {
+            cwd: workspacePath,
+            stdio: ['inherit', 'pipe', 'pipe'],
+            shell: isWindows
+        });
+
+        // Set timeout for status check
+        const timeout = setTimeout(() => {
+            if (!resolved) {
+                resolved = true;
+                try {
+                    child.kill('SIGTERM');
+                } catch {
+                    // Ignore kill errors
+                }
+                console.log(chalk.yellow(`\n⚠ Status check timed out after ${STATUS_CHECK_TIMEOUT / 1000} seconds`));
+                resolvePromise({ checked: false, needsPull: false, timedOut: true });
+            }
+        }, STATUS_CHECK_TIMEOUT);
+
+        child.stdout.on('data', (data) => {
+            output += data.toString();
+        });
+
+        child.stderr.on('data', (data) => {
+            output += data.toString();
+        });
+
+        child.on('close', (code) => {
+            if (resolved) return;
+            resolved = true;
+            clearTimeout(timeout);
+
+            // Check output for specific issue indicators from status command
+            // Note: We avoid checking for "remote" as it appears in normal output
+            // ("Checking local files vs remote Magentrix...")
+            const lowerOutput = output.toLowerCase();
+
+            // If everything is in sync, this message appears
+            const isInSync = lowerOutput.includes('all files are up to date') ||
+                             lowerOutput.includes('in sync');
+
+            // Check for specific issue keywords from logFileStatus output
+            const hasConflict = lowerOutput.includes('conflict');
+            const isOutdated = lowerOutput.includes('outdated');
+            const isAhead = lowerOutput.includes('is ahead');
+            const isMissing = lowerOutput.includes('is missing');
+            const hasContentMismatch = lowerOutput.includes('content mismatch');
+            const hasWarnings = lowerOutput.includes('⚠️') || lowerOutput.includes('🛑');
+
+            const needsPull = !isInSync && (hasConflict || isOutdated || isAhead || isMissing || hasContentMismatch || hasWarnings);
+
+            resolvePromise({ checked: code === 0, needsPull, timedOut: false });
+        });
+
+        child.on('error', (err) => {
+            if (resolved) return;
+            resolved = true;
+            clearTimeout(timeout);
+
+            // If we can't check, assume it's fine and let them proceed
+            console.log(chalk.yellow(`\n⚠ Could not check sync status: ${err.message}`));
+            resolvePromise({ checked: false, needsPull: false, timedOut: false });
+        });
+    });
+}
+
+/**
+ * Run a magentrix command from a specific workspace directory.
+ *
+ * @param {string} workspacePath - Path to the Magentrix workspace
+ * @param {string} command - The magentrix command to run (e.g., 'pull', 'publish')
+ * @param {number} timeout - Optional timeout in milliseconds (defaults to COMMAND_TIMEOUT)
+ * @returns {Promise<boolean>} - True if command succeeded
+ */
+async function runCommandFromWorkspace(workspacePath, command, timeout = COMMAND_TIMEOUT) {
+    return new Promise((resolvePromise) => {
+        const isWindows = process.platform === 'win32';
+        const npmCmd = isWindows ? 'npx.cmd' : 'npx';
+
+        let resolved = false;
+
+        const child = spawn(npmCmd, ['magentrix', command], {
+            cwd: workspacePath,
+            stdio: 'inherit',
+            shell: isWindows
+        });
+
+        // Set timeout for command execution
+        const timeoutId = setTimeout(() => {
+            if (!resolved) {
+                resolved = true;
+                try {
+                    child.kill('SIGTERM');
+                } catch {
+                    // Ignore kill errors
+                }
+                console.log();
+                console.log(chalk.red(formatTimeoutError({
+                    operation: `magentrix ${command}`,
+                    timeout: timeout,
+                    suggestion: `The ${command} operation is taking too long. Check your network connection or try again later.`
+                })));
+                resolvePromise(false);
+            }
+        }, timeout);
+
+        child.on('close', (code) => {
+            if (resolved) return;
+            resolved = true;
+            clearTimeout(timeoutId);
+            resolvePromise(code === 0);
+        });
+
+        child.on('error', (err) => {
+            if (resolved) return;
+            resolved = true;
+            clearTimeout(timeoutId);
+            console.log(chalk.yellow(`Warning: Could not run ${command}: ${err.message}`));
+            resolvePromise(false);
+        });
+    });
+}
+
+/**
+ * Prompt user to select a Magentrix workspace.
+ *
+ * @returns {Promise<string | null>} - Selected workspace path or null if cancelled
+ */
+async function selectWorkspace() {
+    const workspaces = getValidWorkspaces();
+
+    if (workspaces.length === 0) {
+        console.log(chalk.yellow('No Magentrix workspaces found.'));
+        console.log();
+        console.log(chalk.gray('To register a workspace:'));
+        console.log(chalk.white(`  • Run ${chalk.cyan('magentrix')} from an existing workspace (auto-registers it)`));
+        console.log(chalk.white(`  • Or run ${chalk.cyan('magentrix setup')} in a new directory to create one`));
+        console.log();
+        console.log(chalk.gray('Or specify a workspace path directly:'));
+        console.log(chalk.white(`  ${chalk.cyan('magentrix vue-run-build --workspace /path/to/workspace')}`));
+        console.log();
+
+        // Allow manual entry
+        const manualPath = await input({
+            message: 'Enter the path to your Magentrix workspace (or leave empty to cancel):',
+            validate: (value) => {
+                if (!value.trim()) return true; // Allow empty for cancel
+                const resolved = resolve(value);
+                if (!existsSync(resolved)) {
+                    return `Path does not exist: ${resolved}`;
+                }
+                const magentrixFolder = join(resolved, '.magentrix');
+                if (!existsSync(magentrixFolder)) {
+                    return `Not a Magentrix workspace (missing .magentrix folder): ${resolved}`;
+                }
+                return true;
+            }
+        });
+
+        if (!manualPath.trim()) {
+            console.log(chalk.gray('Cancelled.'));
+            return null;
+        }
+
+        return resolve(manualPath);
+    }
+
+    // Build choices from registered workspaces
+    const choices = workspaces.map(w => ({
+        name: `${w.path}`,
+        value: w.path,
+        description: chalk.dim(`→ ${w.instanceUrl}`)
+    }));
+
+    choices.push({
+        name: 'Enter path manually',
+        value: '__manual__',
+        description: chalk.dim('→ Specify the full path to a workspace')
+    });
+
+    choices.push({
+        name: 'Cancel',
+        value: '__cancel__'
+    });
+
+    const choice = await select({
+        message: 'Which workspace do you want to stage into?',
+        choices
+    });
+
+    if (choice === '__cancel__') {
+        console.log(chalk.gray('Cancelled.'));
+        return null;
+    }
+
+    if (choice === '__manual__') {
+        const manualPath = await input({
+            message: 'Enter the path to your Magentrix workspace:',
+            validate: (value) => {
+                if (!value.trim()) {
+                    return 'Path is required';
+                }
+                const resolved = resolve(value);
+                if (!existsSync(resolved)) {
+                    return `Path does not exist: ${resolved}`;
+                }
+                const magentrixFolder = join(resolved, '.magentrix');
+                if (!existsSync(magentrixFolder)) {
+                    return `Not a Magentrix workspace (missing .magentrix folder): ${resolved}`;
+                }
+                return true;
+            }
+        });
+
+        return resolve(manualPath);
+    }
+
+    return choice;
+}
+
+/**
+ * Prompt user to select a project.
+ *
+ * @returns {Promise<{path: string, config: object} | null>}
+ */
+async function selectProject() {
+    const projectsWithStatus = getLinkedProjectsWithStatus();
+
+    // Check if CWD is a Vue project (and not already linked)
+    const cwdConfig = readVueConfig(process.cwd());
+    const inVueProject = cwdConfig.found && cwdConfig.errors.length === 0;
+    const cwdAlreadyLinked = projectsWithStatus.some(p =>
+        resolve(p.path) === resolve(process.cwd())
+    );
+
+    // Build choices using the helper
+    const choices = buildProjectChoices({
+        includeManual: true,
+        includeCancel: true,
+        showInvalid: true
+    });
+
+    // If CWD is a valid Vue project and not linked, add it at the top
+    if (inVueProject && !cwdAlreadyLinked) {
+        choices.unshift({
+            name: `${cwdConfig.appName} (${cwdConfig.slug}) - Current directory (not linked)`,
+            value: { type: 'cwd', path: process.cwd() }
+        });
+    }
+
+    // Check if we have any projects to show
+    const hasProjects = choices.some(c => c.value?.type === 'linked' || c.value?.type === 'cwd');
+
+    if (!hasProjects) {
+        console.log(chalk.yellow('No linked Vue projects found.'));
+        console.log();
+        console.log(chalk.gray('To get started:'));
+        console.log(chalk.white(`  1. Link a Vue project: ${chalk.cyan('magentrix iris-app-link')}`));
+        console.log(chalk.white(`  2. Or specify path: ${chalk.cyan('magentrix vue-run-build --path /path/to/vue-project')}`));
+        console.log();
+    }
+
+    const choice = await select({
+        message: 'Which project do you want to build?',
+        choices
+    });
+
+    if (choice.type === 'cancel') {
+        console.log(chalk.gray('Cancelled.'));
+        return null;
+    }
+
+    if (choice.type === 'manual') {
+        const manualPath = await input({
+            message: 'Enter the path to your Vue project:',
+            validate: (value) => {
+                if (!value.trim()) {
+                    return 'Path is required';
+                }
+                const resolved = resolve(value);
+                if (!existsSync(resolved)) {
+                    return `Path does not exist: ${resolved}`;
+                }
+                return true;
+            }
+        });
+
+        const config = readVueConfig(resolve(manualPath));
+        return { path: resolve(manualPath), config };
+    }
+
+    // Linked project or CWD
+    const config = readVueConfig(choice.path);
+    return { path: choice.path, config };
+}
+
+export default vueBuildStage;