@magentrix-corp/magentrix-cli 1.3.16 → 1.3.17

package/actions/iris/dev.js

@@ -1,391 +1,391 @@
-import chalk from 'chalk';
-import { select, input } from '@inquirer/prompts';
-import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { resolve, basename, join } from 'node:path';
-import {
-    readVueConfig,
-    formatMissingConfigError,
-    formatConfigErrors,
-    injectAssets,
-    getInjectionTarget
-} from '../../utils/iris/config-reader.js';
-import { getIrisAssets } from '../../utils/magentrix/api/iris.js';
-import { getAccessToken } from '../../utils/magentrix/api/auth.js';
-import {
-    getLinkedProjectsWithStatus,
-    buildProjectChoices
-} from '../../utils/iris/linker.js';
-import {
-    acquireLock,
-    releaseLock,
-    LockTypes,
-    createProjectContext
-} from '../../utils/iris/lock.js';
-import {
-    formatNetworkError,
-    formatError
-} from '../../utils/iris/errors.js';
-
-/**
- * Timeout for fetching assets (30 seconds).
- */
-const ASSET_FETCH_TIMEOUT = 30000;
-
-/**
- * vue-run-dev command - Start Vue dev server with platform assets injected.
- *
- * Uses credentials from .env.development (VITE_REFRESH_TOKEN, VITE_SITE_URL).
- * Assets are updated in .env.development (VITE_ASSETS) and kept between runs.
- *
- * Options:
- *   --path <dir>      Specify Vue project path
- *   --no-inject       Skip asset injection, just run dev server
- */
-export const irisDev = async (options = {}) => {
-    process.stdout.write('\x1Bc'); // Clear console
-
-    const { path: pathOption, inject = true } = options;
-
-    // Determine which project to use
-    let projectPath = pathOption;
-    let vueConfig = null;
-
-    if (projectPath) {
-        projectPath = resolve(projectPath);
-
-        if (!existsSync(projectPath)) {
-            console.log(chalk.red(`Error: Path does not exist: ${projectPath}`));
-            return;
-        }
-
-        vueConfig = readVueConfig(projectPath);
-    } else {
-        // Try current directory first
-        const cwdConfig = readVueConfig(process.cwd());
-        if (cwdConfig.found && cwdConfig.errors.length === 0) {
-            projectPath = process.cwd();
-            vueConfig = cwdConfig;
-            console.log(chalk.gray(`Using current directory: ${projectPath}`));
-        } else {
-            // Prompt user to select a project
-            const result = await selectProject();
-            if (!result) return;
-
-            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, siteUrl } = vueConfig;
-
-    console.log(chalk.blue('\nIris Development Server'));
-    console.log(chalk.gray('─'.repeat(48)));
-    console.log(chalk.white(`  Project: ${chalk.cyan(appName)} (${slug})`));
-    console.log(chalk.white(`  Path: ${chalk.gray(projectPath)}`));
-    if (siteUrl) {
-        console.log(chalk.white(`  Site: ${chalk.gray(siteUrl)}`));
-    }
-    console.log();
-
-    // Inject assets if enabled
-    if (inject && siteUrl) {
-        // Check if we have the refresh token for authentication
-        if (!vueConfig.refreshToken) {
-            console.log(chalk.yellow('Warning: VITE_REFRESH_TOKEN not set in .env.development'));
-            console.log(chalk.gray('Asset injection requires authentication. Continuing without assets.'));
-        } else {
-            console.log(chalk.blue('Fetching platform assets...'));
-
-            try {
-                // Get access token using the refresh token from .env.development
-                // Use Promise.race to implement timeout
-                const tokenPromise = getAccessToken(vueConfig.refreshToken, siteUrl);
-                const timeoutPromise = new Promise((_, reject) =>
-                    setTimeout(() => reject(new Error('Request timed out')), ASSET_FETCH_TIMEOUT)
-                );
-
-                const tokenData = await Promise.race([tokenPromise, timeoutPromise]);
-
-                // Fetch assets with timeout
-                const assetsPromise = getIrisAssets(siteUrl, tokenData.token);
-                const assetsResult = await Promise.race([assetsPromise, timeoutPromise]);
-
-                if (assetsResult.success && assetsResult.assets?.length > 0) {
-                    console.log(chalk.green(`\u2713 Found ${assetsResult.assets.length} platform assets`));
-
-                    // Determine which file will be modified
-                    const { targetFile } = getInjectionTarget(projectPath);
-
-                    if (!targetFile) {
-                        console.log(chalk.yellow('Warning: No .env.development file found. Cannot inject assets.'));
-                        console.log(chalk.gray('Create a .env.development file to enable asset injection.'));
-                    } else {
-                        // Inject assets (no backup needed - we keep the changes)
-                        console.log(chalk.blue('Updating assets in .env.development...'));
-                        const injectResult = injectAssets(projectPath, assetsResult.assets);
-
-                        if (injectResult.success) {
-                            console.log(chalk.green(`\u2713 Assets updated in ${injectResult.targetName}`));
-                        } else {
-                            // Show specific error if available
-                            if (injectResult.error) {
-                                console.log(chalk.yellow(`Warning: Could not inject assets: ${injectResult.error}`));
-                            } else {
-                                console.log(chalk.yellow('Warning: Could not inject assets. Continuing without injection.'));
-                            }
-                        }
-                    }
-                } else if (assetsResult.error) {
-                    console.log(chalk.yellow(`Warning: Could not fetch assets: ${assetsResult.error}`));
-                    console.log(chalk.gray('Continuing without asset injection.'));
-                } else {
-                    console.log(chalk.yellow('No platform assets found.'));
-                }
-            } catch (err) {
-                // Provide more helpful error messages based on error type
-                if (err.message === 'Request timed out') {
-                    console.log(chalk.yellow('Warning: Asset fetch timed out.'));
-                    console.log(chalk.gray('Check your network connection or try again later.'));
-                } else if (err.code === 'ENOTFOUND' || err.code === 'ECONNREFUSED' || err.code === 'ETIMEDOUT') {
-                    console.log(chalk.yellow(formatNetworkError({
-                        operation: 'fetch assets',
-                        url: siteUrl,
-                        error: err
-                    })));
-                } else if (err.message?.includes('401') || err.message?.includes('Unauthorized')) {
-                    console.log(chalk.yellow('Warning: Authentication failed.'));
-                    console.log(chalk.gray('Your VITE_REFRESH_TOKEN may be invalid or expired.'));
-                    console.log(chalk.gray('Get a new API key from your Magentrix platform.'));
-                } else {
-                    console.log(chalk.yellow(`Warning: Error fetching assets: ${err.message}`));
-                }
-                console.log(chalk.gray('Continuing without asset injection.'));
-            }
-        }
-    } else if (!inject) {
-        console.log(chalk.gray('Skipping asset injection (--no-inject)'));
-    } else if (!siteUrl) {
-        console.log(chalk.yellow('Warning: No siteUrl found. Cannot fetch platform assets.'));
-        console.log(chalk.gray('Set VITE_SITE_URL in .env.development'));
-    }
-
-    // Start dev server
-    console.log();
-    console.log(chalk.blue('Starting development server...'));
-    console.log(chalk.gray('Press Ctrl+C to stop'));
-    console.log();
-
-    await runDevServer(projectPath);
-};
-
-/**
- * Run the Vue development server.
- *
- * @param {string} projectPath - Path to the Vue project
- * @returns {Promise<number>} - Exit code
- */
-async function runDevServer(projectPath) {
-    // Acquire dev server lock to prevent multiple instances
-    // Use user home for consistent lock location across projects
-    const lockContext = createProjectContext(projectPath);
-    const lockBasePath = join(process.env.HOME || process.env.USERPROFILE || '/tmp', '.magentrix-locks');
-    const lockResult = acquireLock(LockTypes.DEV_SERVER, {
-        context: lockContext,
-        operation: `dev server for ${basename(projectPath)}`,
-        basePath: lockBasePath
-    });
-
-    // Track if lock was acquired (permission errors are non-fatal)
-    let lockAcquired = lockResult.acquired;
-    if (!lockResult.acquired) {
-        if (lockResult.error?.includes('permission') || lockResult.error?.includes('EACCES')) {
-            console.log(chalk.yellow('Warning: Could not create dev server lock (permission issue). Proceeding without lock.'));
-            lockAcquired = false;
-        } else {
-            console.log(chalk.red('Cannot start dev server:'));
-            console.log(chalk.yellow(lockResult.error));
-            return 1;
-        }
-    }
-
-    return new Promise((resolvePromise) => {
-        const isWindows = process.platform === 'win32';
-        const npmCmd = isWindows ? 'npm.cmd' : 'npm';
-
-        const child = spawn(npmCmd, ['run', 'dev'], {
-            cwd: projectPath,
-            stdio: 'inherit',
-            shell: isWindows  // Windows requires shell: true for .cmd files
-        });
-
-        // Cleanup function to release lock
-        const cleanup = () => {
-            if (lockAcquired) {
-                releaseLock(LockTypes.DEV_SERVER, { context: lockContext, basePath: lockBasePath });
-            }
-        };
-
-        // Handle process signals - use once() to avoid memory leaks
-        const handleSignal = (signal) => {
-            cleanup();
-            child.kill(signal);
-            // Give child process a moment to exit, then force exit
-            setTimeout(() => {
-                process.exit(0);
-            }, 500);
-        };
-
-        const sigintHandler = () => handleSignal('SIGINT');
-        const sigtermHandler = () => handleSignal('SIGTERM');
-
-        process.once('SIGINT', sigintHandler);
-        process.once('SIGTERM', sigtermHandler);
-
-        // Remove handlers when child exits to avoid memory leaks
-        child.on('exit', () => {
-            process.removeListener('SIGINT', sigintHandler);
-            process.removeListener('SIGTERM', sigtermHandler);
-        });
-
-        child.on('close', (code) => {
-            cleanup();
-
-            // If dev server exited with error, show helpful context
-            if (code !== 0 && code !== null) {
-                console.log();
-                console.log(chalk.bgYellow.black(' External Process Error '));
-                console.log(chalk.yellow('─'.repeat(48)));
-                console.log(chalk.white('The Vue dev server exited with an error.'));
-                console.log(chalk.gray('This is NOT a MagentrixCLI issue.'));
-                console.log();
-                console.log(chalk.white('Common causes:'));
-                console.log(chalk.gray('  • Permission issues in node_modules/'));
-                console.log(chalk.gray('  • Missing dependencies (run npm install)'));
-                console.log(chalk.gray('  • Port already in use'));
-                console.log(chalk.gray('  • Syntax errors in project files'));
-                console.log();
-                console.log(chalk.white('If you see EACCES/permission errors, try:'));
-                if (isWindows) {
-                    console.log(chalk.cyan('  Run terminal as Administrator'));
-                    console.log(chalk.cyan(`  rd /s /q "${projectPath}\\node_modules"`));
-                    console.log(chalk.cyan('  npm install'));
-                } else {
-                    console.log(chalk.cyan(`  sudo chown -R $(whoami) "${projectPath}/node_modules"`));
-                }
-                console.log(chalk.yellow('─'.repeat(48)));
-            }
-
-            resolvePromise(code);
-        });
-
-        child.on('error', (err) => {
-            cleanup();
-            console.log(chalk.red(`Failed to start dev server: ${err.message}`));
-
-            // Provide more specific error messages
-            if (err.code === 'ENOENT') {
-                console.log();
-                console.log(chalk.yellow('npm was not found on your system.'));
-                console.log(chalk.gray('Make sure Node.js is installed and npm is in your PATH.'));
-            } else if (err.code === 'EACCES' || err.code === 'EPERM') {
-                console.log();
-                console.log(chalk.yellow('Permission denied.'));
-                if (isWindows) {
-                    console.log(chalk.gray('Try running the terminal as Administrator.'));
-                } else {
-                    console.log(chalk.gray('Check file permissions for the project directory.'));
-                }
-            }
-
-            resolvePromise(1);
-        });
-    });
-}
-
-/**
- * Prompt user to select a project.
- */
-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-dev --path /path/to/vue-project')}`));
-        console.log();
-    }
-
-    const choice = await select({
-        message: 'Which project do you want to run?',
-        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 irisDev;
+import chalk from 'chalk';
+import { select, input } from '@inquirer/prompts';
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve, basename, join } from 'node:path';
+import {
+    readVueConfig,
+    formatMissingConfigError,
+    formatConfigErrors,
+    injectAssets,
+    getInjectionTarget
+} from '../../utils/iris/config-reader.js';
+import { getIrisAssets } from '../../utils/magentrix/api/iris.js';
+import { getAccessToken } from '../../utils/magentrix/api/auth.js';
+import {
+    getLinkedProjectsWithStatus,
+    buildProjectChoices
+} from '../../utils/iris/linker.js';
+import {
+    acquireLock,
+    releaseLock,
+    LockTypes,
+    createProjectContext
+} from '../../utils/iris/lock.js';
+import {
+    formatNetworkError,
+    formatError
+} from '../../utils/iris/errors.js';
+
+/**
+ * Timeout for fetching assets (30 seconds).
+ */
+const ASSET_FETCH_TIMEOUT = 30000;
+
+/**
+ * vue-run-dev command - Start Vue dev server with platform assets injected.
+ *
+ * Uses credentials from .env.development (VITE_REFRESH_TOKEN, VITE_SITE_URL).
+ * Assets are updated in .env.development (VITE_ASSETS) and kept between runs.
+ *
+ * Options:
+ *   --path <dir>      Specify Vue project path
+ *   --no-inject       Skip asset injection, just run dev server
+ */
+export const irisDev = async (options = {}) => {
+    process.stdout.write('\x1Bc'); // Clear console
+
+    const { path: pathOption, inject = true } = options;
+
+    // Determine which project to use
+    let projectPath = pathOption;
+    let vueConfig = null;
+
+    if (projectPath) {
+        projectPath = resolve(projectPath);
+
+        if (!existsSync(projectPath)) {
+            console.log(chalk.red(`Error: Path does not exist: ${projectPath}`));
+            return;
+        }
+
+        vueConfig = readVueConfig(projectPath);
+    } else {
+        // Try current directory first
+        const cwdConfig = readVueConfig(process.cwd());
+        if (cwdConfig.found && cwdConfig.errors.length === 0) {
+            projectPath = process.cwd();
+            vueConfig = cwdConfig;
+            console.log(chalk.gray(`Using current directory: ${projectPath}`));
+        } else {
+            // Prompt user to select a project
+            const result = await selectProject();
+            if (!result) return;
+
+            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, siteUrl } = vueConfig;
+
+    console.log(chalk.blue('\nIris Development Server'));
+    console.log(chalk.gray('─'.repeat(48)));
+    console.log(chalk.white(`  Project: ${chalk.cyan(appName)} (${slug})`));
+    console.log(chalk.white(`  Path: ${chalk.gray(projectPath)}`));
+    if (siteUrl) {
+        console.log(chalk.white(`  Site: ${chalk.gray(siteUrl)}`));
+    }
+    console.log();
+
+    // Inject assets if enabled
+    if (inject && siteUrl) {
+        // Check if we have the refresh token for authentication
+        if (!vueConfig.refreshToken) {
+            console.log(chalk.yellow('Warning: VITE_REFRESH_TOKEN not set in .env.development'));
+            console.log(chalk.gray('Asset injection requires authentication. Continuing without assets.'));
+        } else {
+            console.log(chalk.blue('Fetching platform assets...'));
+
+            try {
+                // Get access token using the refresh token from .env.development
+                // Use Promise.race to implement timeout
+                const tokenPromise = getAccessToken(vueConfig.refreshToken, siteUrl);
+                const timeoutPromise = new Promise((_, reject) =>
+                    setTimeout(() => reject(new Error('Request timed out')), ASSET_FETCH_TIMEOUT)
+                );
+
+                const tokenData = await Promise.race([tokenPromise, timeoutPromise]);
+
+                // Fetch assets with timeout
+                const assetsPromise = getIrisAssets(siteUrl, tokenData.token);
+                const assetsResult = await Promise.race([assetsPromise, timeoutPromise]);
+
+                if (assetsResult.success && assetsResult.assets?.length > 0) {
+                    console.log(chalk.green(`\u2713 Found ${assetsResult.assets.length} platform assets`));
+
+                    // Determine which file will be modified
+                    const { targetFile } = getInjectionTarget(projectPath);
+
+                    if (!targetFile) {
+                        console.log(chalk.yellow('Warning: No .env.development file found. Cannot inject assets.'));
+                        console.log(chalk.gray('Create a .env.development file to enable asset injection.'));
+                    } else {
+                        // Inject assets (no backup needed - we keep the changes)
+                        console.log(chalk.blue('Updating assets in .env.development...'));
+                        const injectResult = injectAssets(projectPath, assetsResult.assets);
+
+                        if (injectResult.success) {
+                            console.log(chalk.green(`\u2713 Assets updated in ${injectResult.targetName}`));
+                        } else {
+                            // Show specific error if available
+                            if (injectResult.error) {
+                                console.log(chalk.yellow(`Warning: Could not inject assets: ${injectResult.error}`));
+                            } else {
+                                console.log(chalk.yellow('Warning: Could not inject assets. Continuing without injection.'));
+                            }
+                        }
+                    }
+                } else if (assetsResult.error) {
+                    console.log(chalk.yellow(`Warning: Could not fetch assets: ${assetsResult.error}`));
+                    console.log(chalk.gray('Continuing without asset injection.'));
+                } else {
+                    console.log(chalk.yellow('No platform assets found.'));
+                }
+            } catch (err) {
+                // Provide more helpful error messages based on error type
+                if (err.message === 'Request timed out') {
+                    console.log(chalk.yellow('Warning: Asset fetch timed out.'));
+                    console.log(chalk.gray('Check your network connection or try again later.'));
+                } else if (err.code === 'ENOTFOUND' || err.code === 'ECONNREFUSED' || err.code === 'ETIMEDOUT') {
+                    console.log(chalk.yellow(formatNetworkError({
+                        operation: 'fetch assets',
+                        url: siteUrl,
+                        error: err
+                    })));
+                } else if (err.message?.includes('401') || err.message?.includes('Unauthorized')) {
+                    console.log(chalk.yellow('Warning: Authentication failed.'));
+                    console.log(chalk.gray('Your VITE_REFRESH_TOKEN may be invalid or expired.'));
+                    console.log(chalk.gray('Get a new API key from your Magentrix platform.'));
+                } else {
+                    console.log(chalk.yellow(`Warning: Error fetching assets: ${err.message}`));
+                }
+                console.log(chalk.gray('Continuing without asset injection.'));
+            }
+        }
+    } else if (!inject) {
+        console.log(chalk.gray('Skipping asset injection (--no-inject)'));
+    } else if (!siteUrl) {
+        console.log(chalk.yellow('Warning: No siteUrl found. Cannot fetch platform assets.'));
+        console.log(chalk.gray('Set VITE_SITE_URL in .env.development'));
+    }
+
+    // Start dev server
+    console.log();
+    console.log(chalk.blue('Starting development server...'));
+    console.log(chalk.gray('Press Ctrl+C to stop'));
+    console.log();
+
+    await runDevServer(projectPath);
+};
+
+/**
+ * Run the Vue development server.
+ *
+ * @param {string} projectPath - Path to the Vue project
+ * @returns {Promise<number>} - Exit code
+ */
+async function runDevServer(projectPath) {
+    // Acquire dev server lock to prevent multiple instances
+    // Use user home for consistent lock location across projects
+    const lockContext = createProjectContext(projectPath);
+    const lockBasePath = join(process.env.HOME || process.env.USERPROFILE || '/tmp', '.magentrix-locks');
+    const lockResult = acquireLock(LockTypes.DEV_SERVER, {
+        context: lockContext,
+        operation: `dev server for ${basename(projectPath)}`,
+        basePath: lockBasePath
+    });
+
+    // Track if lock was acquired (permission errors are non-fatal)
+    let lockAcquired = lockResult.acquired;
+    if (!lockResult.acquired) {
+        if (lockResult.error?.includes('permission') || lockResult.error?.includes('EACCES')) {
+            console.log(chalk.yellow('Warning: Could not create dev server lock (permission issue). Proceeding without lock.'));
+            lockAcquired = false;
+        } else {
+            console.log(chalk.red('Cannot start dev server:'));
+            console.log(chalk.yellow(lockResult.error));
+            return 1;
+        }
+    }
+
+    return new Promise((resolvePromise) => {
+        const isWindows = process.platform === 'win32';
+        const npmCmd = isWindows ? 'npm.cmd' : 'npm';
+
+        const child = spawn(npmCmd, ['run', 'dev'], {
+            cwd: projectPath,
+            stdio: 'inherit',
+            shell: isWindows  // Windows requires shell: true for .cmd files
+        });
+
+        // Cleanup function to release lock
+        const cleanup = () => {
+            if (lockAcquired) {
+                releaseLock(LockTypes.DEV_SERVER, { context: lockContext, basePath: lockBasePath });
+            }
+        };
+
+        // Handle process signals - use once() to avoid memory leaks
+        const handleSignal = (signal) => {
+            cleanup();
+            child.kill(signal);
+            // Give child process a moment to exit, then force exit
+            setTimeout(() => {
+                process.exit(0);
+            }, 500);
+        };
+
+        const sigintHandler = () => handleSignal('SIGINT');
+        const sigtermHandler = () => handleSignal('SIGTERM');
+
+        process.once('SIGINT', sigintHandler);
+        process.once('SIGTERM', sigtermHandler);
+
+        // Remove handlers when child exits to avoid memory leaks
+        child.on('exit', () => {
+            process.removeListener('SIGINT', sigintHandler);
+            process.removeListener('SIGTERM', sigtermHandler);
+        });
+
+        child.on('close', (code) => {
+            cleanup();
+
+            // If dev server exited with error, show helpful context
+            if (code !== 0 && code !== null) {
+                console.log();
+                console.log(chalk.bgYellow.black(' External Process Error '));
+                console.log(chalk.yellow('─'.repeat(48)));
+                console.log(chalk.white('The Vue dev server exited with an error.'));
+                console.log(chalk.gray('This is NOT a MagentrixCLI issue.'));
+                console.log();
+                console.log(chalk.white('Common causes:'));
+                console.log(chalk.gray('  • Permission issues in node_modules/'));
+                console.log(chalk.gray('  • Missing dependencies (run npm install)'));
+                console.log(chalk.gray('  • Port already in use'));
+                console.log(chalk.gray('  • Syntax errors in project files'));
+                console.log();
+                console.log(chalk.white('If you see EACCES/permission errors, try:'));
+                if (isWindows) {
+                    console.log(chalk.cyan('  Run terminal as Administrator'));
+                    console.log(chalk.cyan(`  rd /s /q "${projectPath}\\node_modules"`));
+                    console.log(chalk.cyan('  npm install'));
+                } else {
+                    console.log(chalk.cyan(`  sudo chown -R $(whoami) "${projectPath}/node_modules"`));
+                }
+                console.log(chalk.yellow('─'.repeat(48)));
+            }
+
+            resolvePromise(code);
+        });
+
+        child.on('error', (err) => {
+            cleanup();
+            console.log(chalk.red(`Failed to start dev server: ${err.message}`));
+
+            // Provide more specific error messages
+            if (err.code === 'ENOENT') {
+                console.log();
+                console.log(chalk.yellow('npm was not found on your system.'));
+                console.log(chalk.gray('Make sure Node.js is installed and npm is in your PATH.'));
+            } else if (err.code === 'EACCES' || err.code === 'EPERM') {
+                console.log();
+                console.log(chalk.yellow('Permission denied.'));
+                if (isWindows) {
+                    console.log(chalk.gray('Try running the terminal as Administrator.'));
+                } else {
+                    console.log(chalk.gray('Check file permissions for the project directory.'));
+                }
+            }
+
+            resolvePromise(1);
+        });
+    });
+}
+
+/**
+ * Prompt user to select a project.
+ */
+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-dev --path /path/to/vue-project')}`));
+        console.log();
+    }
+
+    const choice = await select({
+        message: 'Which project do you want to run?',
+        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 irisDev;