@magentrix-corp/magentrix-cli 1.3.16 → 1.3.17

package/utils/iris/linker.js

@@ -1,601 +1,601 @@
-import { existsSync } from 'node:fs';
-import { resolve, basename } from 'node:path';
-import Config from '../config.js';
-import { readVueConfig } from './config-reader.js';
-import { validateSlug } from './validation.js';
-import { formatError, formatCorruptedConfigError, detectErrorType, ErrorTypes } from './errors.js';
-
-const config = new Config();
-
-/**
- * Safe wrapper for reading config that handles corruption.
- *
- * @param {string} key - Config key to read
- * @param {Object} options - Config options
- * @returns {{success: boolean, data: any, error: string | null}}
- */
-function safeConfigRead(key, options) {
-    try {
-        const data = config.read(key, options);
-        return { success: true, data, error: null };
-    } catch (err) {
-        const errorType = detectErrorType(err);
-        if (errorType === ErrorTypes.CORRUPTED) {
-            return {
-                success: false,
-                data: null,
-                error: formatCorruptedConfigError({
-                    configPath: config.getGlobalConfigPath?.() || '~/.config/magentrix/config.json',
-                    error: err
-                })
-            };
-        }
-        return { success: false, data: null, error: err.message };
-    }
-}
-
-/**
- * Safe wrapper for saving config that handles errors.
- *
- * @param {string} key - Config key to save
- * @param {any} value - Value to save
- * @param {Object} options - Config options
- * @returns {{success: boolean, error: string | null}}
- */
-function safeConfigSave(key, value, options) {
-    try {
-        config.save(key, value, options);
-        return { success: true, error: null };
-    } catch (err) {
-        const errorType = detectErrorType(err);
-        if (errorType === ErrorTypes.PERMISSION) {
-            return {
-                success: false,
-                error: `Permission denied saving config. Check file permissions for the global config directory.`
-            };
-        }
-        if (errorType === ErrorTypes.DISK_FULL) {
-            return {
-                success: false,
-                error: `Disk full - cannot save config. Free up disk space and try again.`
-            };
-        }
-        return { success: false, error: `Failed to save config: ${err.message}` };
-    }
-}
-
-/**
- * Get all linked Vue projects from global config.
- *
- * @returns {Array<{
- *   path: string,
- *   slug: string,
- *   appName: string,
- *   siteUrl: string | null,
- *   lastBuild: string | null
- * }>}
- */
-export function getLinkedProjects() {
-    const result = safeConfigRead('linkedVueProjects', {
-        global: true  // Store globally so projects persist across Magentrix workspaces
-    });
-
-    if (!result.success) {
-        // Log error but return empty array to allow graceful degradation
-        console.error(result.error);
-        return [];
-    }
-
-    return result.data || [];
-}
-
-/**
- * Save linked projects to global config.
- *
- * @param {Array} projects - Array of linked projects
- * @returns {{success: boolean, error: string | null}}
- */
-function saveLinkedProjects(projects) {
-    return safeConfigSave('linkedVueProjects', projects, {
-        global: true
-    });
-}
-
-/**
- * Validate a linked project and return its current status.
- *
- * @param {{path: string, slug: string, appName: string}} project - Project to validate
- * @returns {{
- *   valid: boolean,
- *   exists: boolean,
- *   hasConfig: boolean,
- *   configValid: boolean,
- *   currentSlug: string | null,
- *   currentAppName: string | null,
- *   errors: string[]
- * }}
- */
-export function validateLinkedProject(project) {
-    const result = {
-        valid: false,
-        exists: false,
-        hasConfig: false,
-        configValid: false,
-        currentSlug: null,
-        currentAppName: null,
-        errors: []
-    };
-
-    // Check if path exists
-    if (!existsSync(project.path)) {
-        result.errors.push('Path no longer exists');
-        return result;
-    }
-    result.exists = true;
-
-    // Check if it's still a valid Vue project
-    const vueConfig = readVueConfig(project.path);
-    if (!vueConfig.found) {
-        result.errors.push('No config.ts found');
-        return result;
-    }
-    result.hasConfig = true;
-
-    // Check for config errors
-    if (vueConfig.errors.length > 0) {
-        result.errors.push(...vueConfig.errors);
-        return result;
-    }
-    result.configValid = true;
-
-    // Store current values (might have changed)
-    result.currentSlug = vueConfig.slug;
-    result.currentAppName = vueConfig.appName;
-    result.valid = true;
-
-    return result;
-}
-
-/**
- * Get all linked projects with their current validation status.
- *
- * @returns {Array<{
- *   path: string,
- *   slug: string,
- *   appName: string,
- *   siteUrl: string | null,
- *   lastBuild: string | null,
- *   validation: {
- *     valid: boolean,
- *     exists: boolean,
- *     hasConfig: boolean,
- *     configValid: boolean,
- *     currentSlug: string | null,
- *     currentAppName: string | null,
- *     errors: string[]
- *   }
- * }>}
- */
-export function getLinkedProjectsWithStatus() {
-    const projects = getLinkedProjects();
-
-    return projects.map(project => ({
-        ...project,
-        validation: validateLinkedProject(project)
-    }));
-}
-
-/**
- * Find a linked project by slug.
- *
- * @param {string} slug - The app slug to find
- * @returns {{
- *   path: string,
- *   slug: string,
- *   appName: string,
- *   siteUrl: string | null,
- *   lastBuild: string | null
- * } | null}
- */
-export function findLinkedProject(slug) {
-    const projects = getLinkedProjects();
-    return projects.find(p => p.slug === slug) || null;
-}
-
-/**
- * Find a linked project by path.
- *
- * @param {string} projectPath - The project path to find
- * @returns {{
- *   path: string,
- *   slug: string,
- *   appName: string,
- *   siteUrl: string | null,
- *   lastBuild: string | null
- * } | null}
- */
-export function findLinkedProjectByPath(projectPath) {
-    const projects = getLinkedProjects();
-    const normalizedPath = resolve(projectPath);
-    return projects.find(p => resolve(p.path) === normalizedPath) || null;
-}
-
-/**
- * Link a Vue project to the CLI (stored globally).
- *
- * @param {string} projectPath - Path to the Vue project
- * @returns {{
- *   success: boolean,
- *   project: {
- *     path: string,
- *     slug: string,
- *     appName: string,
- *     appDescription: string | null,
- *     appIconId: string | null,
- *     siteUrl: string | null,
- *     lastBuild: string | null
- *   } | null,
- *   error: string | null,
- *   updated: boolean
- * }}
- */
-export function linkVueProject(projectPath) {
-    const normalizedPath = resolve(projectPath);
-
-    // Validate the path exists
-    if (!existsSync(normalizedPath)) {
-        return {
-            success: false,
-            project: null,
-            error: `Path does not exist: ${normalizedPath}`,
-            updated: false
-        };
-    }
-
-    // Check if package.json exists (basic Vue project check)
-    const packageJsonPath = resolve(normalizedPath, 'package.json');
-    if (!existsSync(packageJsonPath)) {
-        return {
-            success: false,
-            project: null,
-            error: `Not a valid project directory (no package.json found): ${normalizedPath}`,
-            updated: false
-        };
-    }
-
-    // Read and validate Vue config
-    const vueConfig = readVueConfig(normalizedPath);
-    if (!vueConfig.found) {
-        return {
-            success: false,
-            project: null,
-            error: vueConfig.errors.join('\n'),
-            updated: false
-        };
-    }
-
-    if (vueConfig.errors.length > 0) {
-        return {
-            success: false,
-            project: null,
-            error: `Config validation errors:\n${vueConfig.errors.join('\n')}`,
-            updated: false
-        };
-    }
-
-    // Check if already linked
-    const existing = findLinkedProjectByPath(normalizedPath);
-    if (existing) {
-        // Update existing entry
-        const projects = getLinkedProjects();
-        const index = projects.findIndex(p => resolve(p.path) === normalizedPath);
-        projects[index] = {
-            ...projects[index],
-            slug: vueConfig.slug,
-            appName: vueConfig.appName,
-            appDescription: vueConfig.appDescription,
-            appIconId: vueConfig.appIconId,
-            siteUrl: vueConfig.siteUrl
-        };
-
-        const saveResult = saveLinkedProjects(projects);
-        if (!saveResult.success) {
-            return {
-                success: false,
-                project: null,
-                error: saveResult.error,
-                updated: false
-            };
-        }
-
-        return {
-            success: true,
-            project: projects[index],
-            error: null,
-            updated: true
-        };
-    }
-
-    // Check if slug conflicts with another linked project
-    const conflicting = findLinkedProject(vueConfig.slug);
-    if (conflicting) {
-        return {
-            success: false,
-            project: null,
-            error: `Slug '${vueConfig.slug}' is already used by another linked project: ${conflicting.path}`,
-            updated: false
-        };
-    }
-
-    // Create new linked project entry
-    const newProject = {
-        path: normalizedPath,
-        slug: vueConfig.slug,
-        appName: vueConfig.appName,
-        appDescription: vueConfig.appDescription,
-        appIconId: vueConfig.appIconId,
-        siteUrl: vueConfig.siteUrl,
-        lastBuild: null
-    };
-
-    // Add to linked projects
-    const projects = getLinkedProjects();
-    projects.push(newProject);
-
-    const saveResult = saveLinkedProjects(projects);
-    if (!saveResult.success) {
-        return {
-            success: false,
-            project: null,
-            error: saveResult.error,
-            updated: false
-        };
-    }
-
-    return {
-        success: true,
-        project: newProject,
-        error: null,
-        updated: false
-    };
-}
-
-/**
- * Unlink a Vue project from the CLI.
- *
- * @param {string} projectPathOrSlug - Path to the Vue project or its slug
- * @returns {{
- *   success: boolean,
- *   project: {
- *     path: string,
- *     slug: string,
- *     appName: string
- *   } | null,
- *   error: string | null
- * }}
- */
-export function unlinkVueProject(projectPathOrSlug) {
-    const projects = getLinkedProjects();
-
-    // Try to find by path first
-    let index = projects.findIndex(p => resolve(p.path) === resolve(projectPathOrSlug));
-
-    // If not found by path, try by slug
-    if (index === -1) {
-        index = projects.findIndex(p => p.slug === projectPathOrSlug);
-    }
-
-    if (index === -1) {
-        return {
-            success: false,
-            project: null,
-            error: `No linked project found for: ${projectPathOrSlug}`
-        };
-    }
-
-    // Remove from list
-    const [removed] = projects.splice(index, 1);
-    const saveResult = saveLinkedProjects(projects);
-
-    if (!saveResult.success) {
-        return {
-            success: false,
-            project: null,
-            error: saveResult.error
-        };
-    }
-
-    return {
-        success: true,
-        project: removed,
-        error: null
-    };
-}
-
-/**
- * Remove all invalid (non-existent paths) linked projects.
- *
- * @returns {{
- *   success: boolean,
- *   removed: number,
- *   projects: Array<{path: string, slug: string, appName: string}>,
- *   error: string | null
- * }}
- */
-export function cleanupInvalidProjects() {
-    const projects = getLinkedProjects();
-    const validProjects = [];
-    const removedProjects = [];
-
-    for (const project of projects) {
-        if (existsSync(project.path)) {
-            validProjects.push(project);
-        } else {
-            removedProjects.push(project);
-        }
-    }
-
-    if (removedProjects.length > 0) {
-        const saveResult = saveLinkedProjects(validProjects);
-        if (!saveResult.success) {
-            return {
-                success: false,
-                removed: 0,
-                projects: [],
-                error: saveResult.error
-            };
-        }
-    }
-
-    return {
-        success: true,
-        removed: removedProjects.length,
-        projects: removedProjects,
-        error: null
-    };
-}
-
-/**
- * Update the last build timestamp for a linked project.
- *
- * @param {string} slug - The app slug
- * @returns {{success: boolean, error: string | null}}
- */
-export function updateLastBuild(slug) {
-    const projects = getLinkedProjects();
-    const index = projects.findIndex(p => p.slug === slug);
-
-    if (index === -1) {
-        return { success: false, error: 'Project not found' };
-    }
-
-    projects[index].lastBuild = new Date().toISOString();
-    const saveResult = saveLinkedProjects(projects);
-
-    return saveResult;
-}
-
-/**
- * Format linked projects list for display.
- *
- * @param {Array} projects - Array of linked projects (with or without validation)
- * @returns {string} - Formatted string for display
- */
-export function formatLinkedProjects(projects) {
-    if (!projects || projects.length === 0) {
-        return 'No Vue projects linked.\n\nUse `magentrix iris-app-link` to link a project.';
-    }
-
-    const lines = [
-        'Linked Vue Projects',
-        '────────────────────────────────────────────────────',
-        ''
-    ];
-
-    for (const project of projects) {
-        const validation = project.validation || validateLinkedProject(project);
-
-        // Status indicator
-        let statusIcon = '✓';
-        let statusColor = '\x1b[32m'; // green
-        if (!validation.valid) {
-            statusIcon = '⚠';
-            statusColor = '\x1b[33m'; // yellow
-        }
-        if (!validation.exists) {
-            statusIcon = '✗';
-            statusColor = '\x1b[31m'; // red
-        }
-
-        const displayName = validation.currentAppName || project.appName;
-        const displaySlug = validation.currentSlug || project.slug;
-
-        lines.push(`  ${statusColor}${statusIcon}\x1b[0m ${displayName} (${displaySlug})`);
-        lines.push(`    Path: ${project.path}`);
-
-        if (project.siteUrl) {
-            lines.push(`    Site: ${project.siteUrl}`);
-        }
-
-        if (project.lastBuild) {
-            const date = new Date(project.lastBuild);
-            lines.push(`    Last build: ${date.toLocaleString()}`);
-        } else {
-            lines.push(`    Last build: Never`);
-        }
-
-        // Show validation errors
-        if (!validation.valid && validation.errors.length > 0) {
-            lines.push(`    \x1b[33mWarning: ${validation.errors.join(', ')}\x1b[0m`);
-        }
-
-        lines.push('');
-    }
-
-    return lines.join('\n');
-}
-
-/**
- * Build choices array for inquirer select prompt.
- *
- * @param {Object} options - Options for building choices
- * @param {boolean} options.includeManual - Include "Enter path manually" option
- * @param {boolean} options.includeCancel - Include "Cancel" option
- * @param {boolean} options.showInvalid - Show invalid projects (disabled)
- * @returns {Array} - Choices array for select prompt
- */
-export function buildProjectChoices(options = {}) {
-    const {
-        includeManual = true,
-        includeCancel = true,
-        showInvalid = true
-    } = options;
-
-    const projectsWithStatus = getLinkedProjectsWithStatus();
-    const choices = [];
-
-    // Add valid projects first
-    for (const project of projectsWithStatus) {
-        if (project.validation.valid) {
-            const displayName = project.validation.currentAppName || project.appName;
-            const displaySlug = project.validation.currentSlug || project.slug;
-
-            choices.push({
-                name: `${displayName} (${displaySlug})`,
-                value: { type: 'linked', path: project.path, slug: displaySlug }
-            });
-        }
-    }
-
-    // Add invalid projects (disabled) if requested
-    if (showInvalid) {
-        for (const project of projectsWithStatus) {
-            if (!project.validation.valid) {
-                const errorMsg = project.validation.errors[0] || 'Invalid';
-                choices.push({
-                    name: `⚠ ${project.appName} (${project.slug})`,
-                    value: { type: 'invalid', path: project.path },
-                    disabled: errorMsg
-                });
-            }
-        }
-    }
-
-    // Add manual entry option
-    if (includeManual) {
-        choices.push({
-            name: 'Enter path manually',
-            value: { type: 'manual' }
-        });
-    }
-
-    // Add cancel option
-    if (includeCancel) {
-        choices.push({
-            name: 'Cancel',
-            value: { type: 'cancel' }
-        });
-    }
-
-    return choices;
-}
+import { existsSync } from 'node:fs';
+import { resolve, basename } from 'node:path';
+import Config from '../config.js';
+import { readVueConfig } from './config-reader.js';
+import { validateSlug } from './validation.js';
+import { formatError, formatCorruptedConfigError, detectErrorType, ErrorTypes } from './errors.js';
+
+const config = new Config();
+
+/**
+ * Safe wrapper for reading config that handles corruption.
+ *
+ * @param {string} key - Config key to read
+ * @param {Object} options - Config options
+ * @returns {{success: boolean, data: any, error: string | null}}
+ */
+function safeConfigRead(key, options) {
+    try {
+        const data = config.read(key, options);
+        return { success: true, data, error: null };
+    } catch (err) {
+        const errorType = detectErrorType(err);
+        if (errorType === ErrorTypes.CORRUPTED) {
+            return {
+                success: false,
+                data: null,
+                error: formatCorruptedConfigError({
+                    configPath: config.getGlobalConfigPath?.() || '~/.config/magentrix/config.json',
+                    error: err
+                })
+            };
+        }
+        return { success: false, data: null, error: err.message };
+    }
+}
+
+/**
+ * Safe wrapper for saving config that handles errors.
+ *
+ * @param {string} key - Config key to save
+ * @param {any} value - Value to save
+ * @param {Object} options - Config options
+ * @returns {{success: boolean, error: string | null}}
+ */
+function safeConfigSave(key, value, options) {
+    try {
+        config.save(key, value, options);
+        return { success: true, error: null };
+    } catch (err) {
+        const errorType = detectErrorType(err);
+        if (errorType === ErrorTypes.PERMISSION) {
+            return {
+                success: false,
+                error: `Permission denied saving config. Check file permissions for the global config directory.`
+            };
+        }
+        if (errorType === ErrorTypes.DISK_FULL) {
+            return {
+                success: false,
+                error: `Disk full - cannot save config. Free up disk space and try again.`
+            };
+        }
+        return { success: false, error: `Failed to save config: ${err.message}` };
+    }
+}
+
+/**
+ * Get all linked Vue projects from global config.
+ *
+ * @returns {Array<{
+ *   path: string,
+ *   slug: string,
+ *   appName: string,
+ *   siteUrl: string | null,
+ *   lastBuild: string | null
+ * }>}
+ */
+export function getLinkedProjects() {
+    const result = safeConfigRead('linkedVueProjects', {
+        global: true  // Store globally so projects persist across Magentrix workspaces
+    });
+
+    if (!result.success) {
+        // Log error but return empty array to allow graceful degradation
+        console.error(result.error);
+        return [];
+    }
+
+    return result.data || [];
+}
+
+/**
+ * Save linked projects to global config.
+ *
+ * @param {Array} projects - Array of linked projects
+ * @returns {{success: boolean, error: string | null}}
+ */
+function saveLinkedProjects(projects) {
+    return safeConfigSave('linkedVueProjects', projects, {
+        global: true
+    });
+}
+
+/**
+ * Validate a linked project and return its current status.
+ *
+ * @param {{path: string, slug: string, appName: string}} project - Project to validate
+ * @returns {{
+ *   valid: boolean,
+ *   exists: boolean,
+ *   hasConfig: boolean,
+ *   configValid: boolean,
+ *   currentSlug: string | null,
+ *   currentAppName: string | null,
+ *   errors: string[]
+ * }}
+ */
+export function validateLinkedProject(project) {
+    const result = {
+        valid: false,
+        exists: false,
+        hasConfig: false,
+        configValid: false,
+        currentSlug: null,
+        currentAppName: null,
+        errors: []
+    };
+
+    // Check if path exists
+    if (!existsSync(project.path)) {
+        result.errors.push('Path no longer exists');
+        return result;
+    }
+    result.exists = true;
+
+    // Check if it's still a valid Vue project
+    const vueConfig = readVueConfig(project.path);
+    if (!vueConfig.found) {
+        result.errors.push('No config.ts found');
+        return result;
+    }
+    result.hasConfig = true;
+
+    // Check for config errors
+    if (vueConfig.errors.length > 0) {
+        result.errors.push(...vueConfig.errors);
+        return result;
+    }
+    result.configValid = true;
+
+    // Store current values (might have changed)
+    result.currentSlug = vueConfig.slug;
+    result.currentAppName = vueConfig.appName;
+    result.valid = true;
+
+    return result;
+}
+
+/**
+ * Get all linked projects with their current validation status.
+ *
+ * @returns {Array<{
+ *   path: string,
+ *   slug: string,
+ *   appName: string,
+ *   siteUrl: string | null,
+ *   lastBuild: string | null,
+ *   validation: {
+ *     valid: boolean,
+ *     exists: boolean,
+ *     hasConfig: boolean,
+ *     configValid: boolean,
+ *     currentSlug: string | null,
+ *     currentAppName: string | null,
+ *     errors: string[]
+ *   }
+ * }>}
+ */
+export function getLinkedProjectsWithStatus() {
+    const projects = getLinkedProjects();
+
+    return projects.map(project => ({
+        ...project,
+        validation: validateLinkedProject(project)
+    }));
+}
+
+/**
+ * Find a linked project by slug.
+ *
+ * @param {string} slug - The app slug to find
+ * @returns {{
+ *   path: string,
+ *   slug: string,
+ *   appName: string,
+ *   siteUrl: string | null,
+ *   lastBuild: string | null
+ * } | null}
+ */
+export function findLinkedProject(slug) {
+    const projects = getLinkedProjects();
+    return projects.find(p => p.slug === slug) || null;
+}
+
+/**
+ * Find a linked project by path.
+ *
+ * @param {string} projectPath - The project path to find
+ * @returns {{
+ *   path: string,
+ *   slug: string,
+ *   appName: string,
+ *   siteUrl: string | null,
+ *   lastBuild: string | null
+ * } | null}
+ */
+export function findLinkedProjectByPath(projectPath) {
+    const projects = getLinkedProjects();
+    const normalizedPath = resolve(projectPath);
+    return projects.find(p => resolve(p.path) === normalizedPath) || null;
+}
+
+/**
+ * Link a Vue project to the CLI (stored globally).
+ *
+ * @param {string} projectPath - Path to the Vue project
+ * @returns {{
+ *   success: boolean,
+ *   project: {
+ *     path: string,
+ *     slug: string,
+ *     appName: string,
+ *     appDescription: string | null,
+ *     appIconId: string | null,
+ *     siteUrl: string | null,
+ *     lastBuild: string | null
+ *   } | null,
+ *   error: string | null,
+ *   updated: boolean
+ * }}
+ */
+export function linkVueProject(projectPath) {
+    const normalizedPath = resolve(projectPath);
+
+    // Validate the path exists
+    if (!existsSync(normalizedPath)) {
+        return {
+            success: false,
+            project: null,
+            error: `Path does not exist: ${normalizedPath}`,
+            updated: false
+        };
+    }
+
+    // Check if package.json exists (basic Vue project check)
+    const packageJsonPath = resolve(normalizedPath, 'package.json');
+    if (!existsSync(packageJsonPath)) {
+        return {
+            success: false,
+            project: null,
+            error: `Not a valid project directory (no package.json found): ${normalizedPath}`,
+            updated: false
+        };
+    }
+
+    // Read and validate Vue config
+    const vueConfig = readVueConfig(normalizedPath);
+    if (!vueConfig.found) {
+        return {
+            success: false,
+            project: null,
+            error: vueConfig.errors.join('\n'),
+            updated: false
+        };
+    }
+
+    if (vueConfig.errors.length > 0) {
+        return {
+            success: false,
+            project: null,
+            error: `Config validation errors:\n${vueConfig.errors.join('\n')}`,
+            updated: false
+        };
+    }
+
+    // Check if already linked
+    const existing = findLinkedProjectByPath(normalizedPath);
+    if (existing) {
+        // Update existing entry
+        const projects = getLinkedProjects();
+        const index = projects.findIndex(p => resolve(p.path) === normalizedPath);
+        projects[index] = {
+            ...projects[index],
+            slug: vueConfig.slug,
+            appName: vueConfig.appName,
+            appDescription: vueConfig.appDescription,
+            appIconId: vueConfig.appIconId,
+            siteUrl: vueConfig.siteUrl
+        };
+
+        const saveResult = saveLinkedProjects(projects);
+        if (!saveResult.success) {
+            return {
+                success: false,
+                project: null,
+                error: saveResult.error,
+                updated: false
+            };
+        }
+
+        return {
+            success: true,
+            project: projects[index],
+            error: null,
+            updated: true
+        };
+    }
+
+    // Check if slug conflicts with another linked project
+    const conflicting = findLinkedProject(vueConfig.slug);
+    if (conflicting) {
+        return {
+            success: false,
+            project: null,
+            error: `Slug '${vueConfig.slug}' is already used by another linked project: ${conflicting.path}`,
+            updated: false
+        };
+    }
+
+    // Create new linked project entry
+    const newProject = {
+        path: normalizedPath,
+        slug: vueConfig.slug,
+        appName: vueConfig.appName,
+        appDescription: vueConfig.appDescription,
+        appIconId: vueConfig.appIconId,
+        siteUrl: vueConfig.siteUrl,
+        lastBuild: null
+    };
+
+    // Add to linked projects
+    const projects = getLinkedProjects();
+    projects.push(newProject);
+
+    const saveResult = saveLinkedProjects(projects);
+    if (!saveResult.success) {
+        return {
+            success: false,
+            project: null,
+            error: saveResult.error,
+            updated: false
+        };
+    }
+
+    return {
+        success: true,
+        project: newProject,
+        error: null,
+        updated: false
+    };
+}
+
+/**
+ * Unlink a Vue project from the CLI.
+ *
+ * @param {string} projectPathOrSlug - Path to the Vue project or its slug
+ * @returns {{
+ *   success: boolean,
+ *   project: {
+ *     path: string,
+ *     slug: string,
+ *     appName: string
+ *   } | null,
+ *   error: string | null
+ * }}
+ */
+export function unlinkVueProject(projectPathOrSlug) {
+    const projects = getLinkedProjects();
+
+    // Try to find by path first
+    let index = projects.findIndex(p => resolve(p.path) === resolve(projectPathOrSlug));
+
+    // If not found by path, try by slug
+    if (index === -1) {
+        index = projects.findIndex(p => p.slug === projectPathOrSlug);
+    }
+
+    if (index === -1) {
+        return {
+            success: false,
+            project: null,
+            error: `No linked project found for: ${projectPathOrSlug}`
+        };
+    }
+
+    // Remove from list
+    const [removed] = projects.splice(index, 1);
+    const saveResult = saveLinkedProjects(projects);
+
+    if (!saveResult.success) {
+        return {
+            success: false,
+            project: null,
+            error: saveResult.error
+        };
+    }
+
+    return {
+        success: true,
+        project: removed,
+        error: null
+    };
+}
+
+/**
+ * Remove all invalid (non-existent paths) linked projects.
+ *
+ * @returns {{
+ *   success: boolean,
+ *   removed: number,
+ *   projects: Array<{path: string, slug: string, appName: string}>,
+ *   error: string | null
+ * }}
+ */
+export function cleanupInvalidProjects() {
+    const projects = getLinkedProjects();
+    const validProjects = [];
+    const removedProjects = [];
+
+    for (const project of projects) {
+        if (existsSync(project.path)) {
+            validProjects.push(project);
+        } else {
+            removedProjects.push(project);
+        }
+    }
+
+    if (removedProjects.length > 0) {
+        const saveResult = saveLinkedProjects(validProjects);
+        if (!saveResult.success) {
+            return {
+                success: false,
+                removed: 0,
+                projects: [],
+                error: saveResult.error
+            };
+        }
+    }
+
+    return {
+        success: true,
+        removed: removedProjects.length,
+        projects: removedProjects,
+        error: null
+    };
+}
+
+/**
+ * Update the last build timestamp for a linked project.
+ *
+ * @param {string} slug - The app slug
+ * @returns {{success: boolean, error: string | null}}
+ */
+export function updateLastBuild(slug) {
+    const projects = getLinkedProjects();
+    const index = projects.findIndex(p => p.slug === slug);
+
+    if (index === -1) {
+        return { success: false, error: 'Project not found' };
+    }
+
+    projects[index].lastBuild = new Date().toISOString();
+    const saveResult = saveLinkedProjects(projects);
+
+    return saveResult;
+}
+
+/**
+ * Format linked projects list for display.
+ *
+ * @param {Array} projects - Array of linked projects (with or without validation)
+ * @returns {string} - Formatted string for display
+ */
+export function formatLinkedProjects(projects) {
+    if (!projects || projects.length === 0) {
+        return 'No Vue projects linked.\n\nUse `magentrix iris-app-link` to link a project.';
+    }
+
+    const lines = [
+        'Linked Vue Projects',
+        '────────────────────────────────────────────────────',
+        ''
+    ];
+
+    for (const project of projects) {
+        const validation = project.validation || validateLinkedProject(project);
+
+        // Status indicator
+        let statusIcon = '✓';
+        let statusColor = '\x1b[32m'; // green
+        if (!validation.valid) {
+            statusIcon = '⚠';
+            statusColor = '\x1b[33m'; // yellow
+        }
+        if (!validation.exists) {
+            statusIcon = '✗';
+            statusColor = '\x1b[31m'; // red
+        }
+
+        const displayName = validation.currentAppName || project.appName;
+        const displaySlug = validation.currentSlug || project.slug;
+
+        lines.push(`  ${statusColor}${statusIcon}\x1b[0m ${displayName} (${displaySlug})`);
+        lines.push(`    Path: ${project.path}`);
+
+        if (project.siteUrl) {
+            lines.push(`    Site: ${project.siteUrl}`);
+        }
+
+        if (project.lastBuild) {
+            const date = new Date(project.lastBuild);
+            lines.push(`    Last build: ${date.toLocaleString()}`);
+        } else {
+            lines.push(`    Last build: Never`);
+        }
+
+        // Show validation errors
+        if (!validation.valid && validation.errors.length > 0) {
+            lines.push(`    \x1b[33mWarning: ${validation.errors.join(', ')}\x1b[0m`);
+        }
+
+        lines.push('');
+    }
+
+    return lines.join('\n');
+}
+
+/**
+ * Build choices array for inquirer select prompt.
+ *
+ * @param {Object} options - Options for building choices
+ * @param {boolean} options.includeManual - Include "Enter path manually" option
+ * @param {boolean} options.includeCancel - Include "Cancel" option
+ * @param {boolean} options.showInvalid - Show invalid projects (disabled)
+ * @returns {Array} - Choices array for select prompt
+ */
+export function buildProjectChoices(options = {}) {
+    const {
+        includeManual = true,
+        includeCancel = true,
+        showInvalid = true
+    } = options;
+
+    const projectsWithStatus = getLinkedProjectsWithStatus();
+    const choices = [];
+
+    // Add valid projects first
+    for (const project of projectsWithStatus) {
+        if (project.validation.valid) {
+            const displayName = project.validation.currentAppName || project.appName;
+            const displaySlug = project.validation.currentSlug || project.slug;
+
+            choices.push({
+                name: `${displayName} (${displaySlug})`,
+                value: { type: 'linked', path: project.path, slug: displaySlug }
+            });
+        }
+    }
+
+    // Add invalid projects (disabled) if requested
+    if (showInvalid) {
+        for (const project of projectsWithStatus) {
+            if (!project.validation.valid) {
+                const errorMsg = project.validation.errors[0] || 'Invalid';
+                choices.push({
+                    name: `⚠ ${project.appName} (${project.slug})`,
+                    value: { type: 'invalid', path: project.path },
+                    disabled: errorMsg
+                });
+            }
+        }
+    }
+
+    // Add manual entry option
+    if (includeManual) {
+        choices.push({
+            name: 'Enter path manually',
+            value: { type: 'manual' }
+        });
+    }
+
+    // Add cancel option
+    if (includeCancel) {
+        choices.push({
+            name: 'Cancel',
+            value: { type: 'cancel' }
+        });
+    }
+
+    return choices;
+}