@magentrix-corp/magentrix-cli 1.2.1 → 1.3.0

package/utils/iris/validator.js

@@ -0,0 +1,281 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Required file patterns for a valid Iris build.
+ */
+const REQUIRED_FILES = {
+    remoteEntry: {
+        pattern: /^remoteEntry\.js$/,
+        location: 'root',
+        description: 'remoteEntry.js (required at dist root)'
+    },
+    hostInit: {
+        pattern: /^hostInit.*\.js$/,
+        location: 'assets',
+        description: 'assets/hostInit*.js (required in assets folder)'
+    },
+    main: {
+        pattern: /^main.*\.js$/,
+        location: 'assets',
+        description: 'assets/main*.js (required in assets folder)'
+    },
+    index: {
+        pattern: /^index.*\.js$/,
+        location: 'assets',
+        description: 'assets/index*.js (required in assets folder)'
+    }
+};
+
+/**
+ * Validate that a build output directory contains all required Iris files.
+ *
+ * @param {string} distPath - Path to the build output directory (e.g., ./dist)
+ * @returns {{
+ *   valid: boolean,
+ *   errors: string[],
+ *   warnings: string[],
+ *   files: {
+ *     remoteEntry: string | null,
+ *     hostInit: string | null,
+ *     main: string | null,
+ *     index: string | null
+ *   },
+ *   assetsPath: string | null
+ * }}
+ */
+export function validateIrisBuild(distPath) {
+    const result = {
+        valid: true,
+        errors: [],
+        warnings: [],
+        files: {
+            remoteEntry: null,
+            hostInit: null,
+            main: null,
+            index: null
+        },
+        assetsPath: null
+    };
+
+    // Check if dist path exists
+    if (!existsSync(distPath)) {
+        result.valid = false;
+        result.errors.push(`Build output directory not found: ${distPath}`);
+        return result;
+    }
+
+    // Check if it's a directory
+    const distStat = statSync(distPath);
+    if (!distStat.isDirectory()) {
+        result.valid = false;
+        result.errors.push(`Build output path is not a directory: ${distPath}`);
+        return result;
+    }
+
+    // Get root files
+    let rootFiles;
+    try {
+        rootFiles = readdirSync(distPath);
+    } catch (err) {
+        result.valid = false;
+        result.errors.push(`Failed to read build directory: ${err.message}`);
+        return result;
+    }
+
+    // Check for remoteEntry.js in root
+    const remoteEntryFile = rootFiles.find(f => REQUIRED_FILES.remoteEntry.pattern.test(f));
+    if (remoteEntryFile) {
+        result.files.remoteEntry = path.join(distPath, remoteEntryFile);
+    } else {
+        result.valid = false;
+        result.errors.push(REQUIRED_FILES.remoteEntry.description);
+    }
+
+    // Check for assets directory
+    const assetsDir = rootFiles.find(f => f.toLowerCase() === 'assets');
+    if (!assetsDir) {
+        result.valid = false;
+        result.errors.push('assets/ directory not found in build output');
+        return result;
+    }
+
+    const assetsPath = path.join(distPath, assetsDir);
+    result.assetsPath = assetsPath;
+
+    // Check if assets is a directory
+    const assetsStat = statSync(assetsPath);
+    if (!assetsStat.isDirectory()) {
+        result.valid = false;
+        result.errors.push('assets is not a directory');
+        return result;
+    }
+
+    // Get assets files
+    let assetsFiles;
+    try {
+        assetsFiles = readdirSync(assetsPath);
+    } catch (err) {
+        result.valid = false;
+        result.errors.push(`Failed to read assets directory: ${err.message}`);
+        return result;
+    }
+
+    // Check for required files in assets
+    const hostInitFile = assetsFiles.find(f => REQUIRED_FILES.hostInit.pattern.test(f));
+    if (hostInitFile) {
+        result.files.hostInit = path.join(assetsPath, hostInitFile);
+    } else {
+        result.valid = false;
+        result.errors.push(REQUIRED_FILES.hostInit.description);
+    }
+
+    const mainFile = assetsFiles.find(f => REQUIRED_FILES.main.pattern.test(f));
+    if (mainFile) {
+        result.files.main = path.join(assetsPath, mainFile);
+    } else {
+        result.valid = false;
+        result.errors.push(REQUIRED_FILES.main.description);
+    }
+
+    const indexFile = assetsFiles.find(f => REQUIRED_FILES.index.pattern.test(f));
+    if (indexFile) {
+        result.files.index = path.join(assetsPath, indexFile);
+    } else {
+        result.valid = false;
+        result.errors.push(REQUIRED_FILES.index.description);
+    }
+
+    // Warnings for potential issues
+    if (rootFiles.includes('index.html')) {
+        result.warnings.push('Found index.html in root - this file is typically not needed for Iris apps');
+    }
+
+    return result;
+}
+
+/**
+ * Format validation errors for display to the user.
+ *
+ * @param {ReturnType<typeof validateIrisBuild>} validation - Validation result
+ * @returns {string} - Formatted error message
+ */
+export function formatValidationErrors(validation) {
+    const lines = [
+        'Invalid Build Output',
+        '────────────────────────────────────────────────────',
+        '',
+        'The build output is missing required Iris files.',
+        '',
+        'Status:'
+    ];
+
+    // Show status of each required file
+    const fileStatus = [
+        {
+            name: 'remoteEntry.js',
+            found: validation.files.remoteEntry !== null,
+            foundName: validation.files.remoteEntry ? path.basename(validation.files.remoteEntry) : null
+        },
+        {
+            name: 'assets/hostInit*.js',
+            found: validation.files.hostInit !== null,
+            foundName: validation.files.hostInit ? path.basename(validation.files.hostInit) : null
+        },
+        {
+            name: 'assets/main*.js',
+            found: validation.files.main !== null,
+            foundName: validation.files.main ? path.basename(validation.files.main) : null
+        },
+        {
+            name: 'assets/index*.js',
+            found: validation.files.index !== null,
+            foundName: validation.files.index ? path.basename(validation.files.index) : null
+        }
+    ];
+
+    for (const file of fileStatus) {
+        if (file.found) {
+            lines.push(`  ✓ ${file.name} (found: ${file.foundName})`);
+        } else {
+            lines.push(`  ✗ ${file.name}`);
+        }
+    }
+
+    lines.push('');
+    lines.push('Expected structure:');
+    lines.push('  dist/');
+    lines.push('  ├── remoteEntry.js');
+    lines.push('  └── assets/');
+    lines.push('      ├── hostInit-[hash].js');
+    lines.push('      ├── main-[hash].js');
+    lines.push('      └── index-[hash].js');
+    lines.push('');
+    lines.push('Make sure your Vue.js project is configured for Module Federation.');
+
+    if (validation.warnings.length > 0) {
+        lines.push('');
+        lines.push('Warnings:');
+        for (const warning of validation.warnings) {
+            lines.push(`  ⚠ ${warning}`);
+        }
+    }
+
+    return lines.join('\n');
+}
+
+/**
+ * Get a summary of found files for successful validation.
+ *
+ * @param {ReturnType<typeof validateIrisBuild>} validation - Validation result
+ * @returns {string} - Summary of found files
+ */
+export function getValidationSummary(validation) {
+    const files = [];
+
+    if (validation.files.remoteEntry) {
+        files.push(`  • ${path.basename(validation.files.remoteEntry)}`);
+    }
+    if (validation.files.hostInit) {
+        files.push(`  • assets/${path.basename(validation.files.hostInit)}`);
+    }
+    if (validation.files.main) {
+        files.push(`  • assets/${path.basename(validation.files.main)}`);
+    }
+    if (validation.files.index) {
+        files.push(`  • assets/${path.basename(validation.files.index)}`);
+    }
+
+    return `Found ${files.length} required files:\n${files.join('\n')}`;
+}
+
+/**
+ * Validate an Iris app folder (already staged, not a dist folder).
+ * This is used to validate apps in src/iris-apps/<slug>/.
+ *
+ * @param {string} appPath - Path to the app folder
+ * @returns {{valid: boolean, errors: string[], slug: string | null}}
+ */
+export function validateIrisAppFolder(appPath) {
+    const result = {
+        valid: true,
+        errors: [],
+        slug: null
+    };
+
+    if (!existsSync(appPath)) {
+        result.valid = false;
+        result.errors.push(`App folder not found: ${appPath}`);
+        return result;
+    }
+
+    result.slug = path.basename(appPath);
+
+    // Use the same validation as build output
+    const validation = validateIrisBuild(appPath);
+
+    result.valid = validation.valid;
+    result.errors = validation.errors;
+
+    return result;
+}

package/utils/iris/zipper.js

@@ -0,0 +1,239 @@
+import { mkdirSync, rmSync, writeFileSync, readFileSync, existsSync, readdirSync, statSync, chmodSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, basename } from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
+import archiver from 'archiver';
+import extractZip from 'extract-zip';
+
+/**
+ * Recursively fix permissions on extracted files.
+ * Sets directories to 0o755 and files to 0o644.
+ * This ensures the current user can read/write/delete the files.
+ *
+ * @param {string} dir - Directory to fix permissions for
+ */
+function fixPermissions(dir) {
+    if (!existsSync(dir)) return;
+
+    try {
+        const stat = statSync(dir);
+        if (stat.isDirectory()) {
+            chmodSync(dir, 0o755);
+            const entries = readdirSync(dir);
+            for (const entry of entries) {
+                fixPermissions(join(dir, entry));
+            }
+        } else {
+            chmodSync(dir, 0o644);
+        }
+    } catch {
+        // Ignore permission errors - best effort
+    }
+}
+
+/**
+ * Create a zip file from a build directory with proper Iris structure.
+ * The zip will contain a single root folder with the app slug.
+ *
+ * @param {string} distPath - Path to the build output directory (e.g., ./dist)
+ * @param {string} appSlug - Slug for the app (becomes the root folder in zip)
+ * @returns {Promise<Buffer>} - The zip file as a Buffer
+ */
+export async function createIrisZip(distPath, appSlug) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+
+        const archive = archiver('zip', {
+            zlib: { level: 9 } // Maximum compression
+        });
+
+        archive.on('data', (chunk) => {
+            chunks.push(chunk);
+        });
+
+        archive.on('error', (err) => {
+            reject(err);
+        });
+
+        archive.on('end', () => {
+            resolve(Buffer.concat(chunks));
+        });
+
+        // Add the dist directory contents under the app slug folder
+        // This creates the structure: appSlug/remoteEntry.js, appSlug/assets/...
+        archive.directory(distPath, appSlug);
+
+        archive.finalize();
+    });
+}
+
+/**
+ * Extract a zip buffer to a directory.
+ *
+ * @param {Buffer} zipBuffer - The zip file as a Buffer
+ * @param {string} outputDir - Directory to extract to
+ * @returns {Promise<string>} - Path to the extracted directory
+ */
+export async function extractIrisZip(zipBuffer, outputDir) {
+    // Create a temporary file to hold the zip
+    const tempDir = join(tmpdir(), `iris-extract-${randomUUID()}`);
+    const tempZipPath = join(tempDir, 'temp.zip');
+
+    try {
+        // Create temp directory
+        mkdirSync(tempDir, { recursive: true });
+
+        // Write buffer to temp file
+        writeFileSync(tempZipPath, zipBuffer);
+
+        // Ensure output directory exists
+        mkdirSync(outputDir, { recursive: true });
+
+        // Extract
+        await extractZip(tempZipPath, { dir: outputDir });
+
+        // Fix permissions so files can be deleted/modified later
+        fixPermissions(outputDir);
+
+        return outputDir;
+    } finally {
+        // Cleanup temp directory
+        try {
+            rmSync(tempDir, { recursive: true, force: true });
+        } catch {
+            // Ignore cleanup errors
+        }
+    }
+}
+
+/**
+ * Get the size of a buffer in human-readable format.
+ *
+ * @param {number} bytes - Size in bytes
+ * @returns {string} - Human-readable size (e.g., "1.2 MB")
+ */
+export function formatFileSize(bytes) {
+    if (bytes === 0) return '0 B';
+
+    const units = ['B', 'KB', 'MB', 'GB'];
+    const k = 1024;
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+    if (i === 0) return `${bytes} ${units[0]}`;
+
+    return `${(bytes / Math.pow(k, i)).toFixed(1)} ${units[i]}`;
+}
+
+/**
+ * Count files in a directory recursively.
+ *
+ * @param {string} dir - Directory path
+ * @returns {number} - Number of files
+ */
+export function countFiles(dir) {
+    if (!existsSync(dir)) return 0;
+
+    let count = 0;
+
+    function walk(currentDir) {
+        const entries = readdirSync(currentDir);
+        for (const entry of entries) {
+            const fullPath = join(currentDir, entry);
+            const stat = statSync(fullPath);
+            if (stat.isDirectory()) {
+                walk(fullPath);
+            } else {
+                count++;
+            }
+        }
+    }
+
+    walk(dir);
+    return count;
+}
+
+/**
+ * Calculate total size of files in a directory recursively.
+ *
+ * @param {string} dir - Directory path
+ * @returns {number} - Total size in bytes
+ */
+export function calculateDirSize(dir) {
+    if (!existsSync(dir)) return 0;
+
+    let totalSize = 0;
+
+    function walk(currentDir) {
+        const entries = readdirSync(currentDir);
+        for (const entry of entries) {
+            const fullPath = join(currentDir, entry);
+            const stat = statSync(fullPath);
+            if (stat.isDirectory()) {
+                walk(fullPath);
+            } else {
+                totalSize += stat.size;
+            }
+        }
+    }
+
+    walk(dir);
+    return totalSize;
+}
+
+/**
+ * Get list of all files in a directory recursively with relative paths.
+ *
+ * @param {string} dir - Directory path
+ * @param {string} basePath - Base path for relative path calculation
+ * @returns {string[]} - Array of relative file paths
+ */
+export function getFilesRecursive(dir, basePath = dir) {
+    if (!existsSync(dir)) return [];
+
+    const files = [];
+
+    function walk(currentDir) {
+        const entries = readdirSync(currentDir);
+        for (const entry of entries) {
+            const fullPath = join(currentDir, entry);
+            const stat = statSync(fullPath);
+            if (stat.isDirectory()) {
+                walk(fullPath);
+            } else {
+                const relativePath = fullPath.slice(basePath.length + 1);
+                files.push(relativePath);
+            }
+        }
+    }
+
+    walk(dir);
+    return files;
+}
+
+/**
+ * Calculate a content hash for an entire Iris app folder.
+ * Hashes all file contents and their relative paths to detect any changes.
+ *
+ * @param {string} dir - Directory path to the Iris app
+ * @returns {string} - SHA256 hash of all files
+ */
+export function hashIrisAppFolder(dir) {
+    if (!existsSync(dir)) return '';
+
+    const hash = createHash('sha256');
+    const files = getFilesRecursive(dir).sort(); // Sort for consistent ordering
+
+    for (const relativePath of files) {
+        const fullPath = join(dir, relativePath);
+        try {
+            const content = readFileSync(fullPath);
+            // Include the relative path in the hash so renames are detected
+            hash.update(relativePath);
+            hash.update(content);
+        } catch {
+            // Skip files we can't read
+        }
+    }
+
+    return hash.digest('hex');
+}

package/utils/logger.js

@@ -129,8 +129,12 @@ export class Logger {
 
     /**
      * Log an error message
+     * @param {string} message - Error message
+     * @param {Error|null} error - Error object
+     * @param {object|null} details - Additional details
+     * @param {string|null} hint - Helpful hint for resolving the error
      */
-    error(message, error = null, details = null) {
+    error(message, error = null, details = null, hint = null) {
         const timestamp = new Date().toISOString();
         const entry = {
             timestamp,
@@ -138,7 +142,8 @@ export class Logger {
             message,
             error: error ? error.toString() : null,
             stack: error?.stack || null,
-            details
+            details,
+            hint
         };
         this.errors.push(entry);
 
@@ -194,13 +199,16 @@ export class Logger {
                 console.log(chalk.red(`  ✗ ${summary.errors} error(s)`));
 
                 // Show preview of recent errors
-                const recentErrors = this.getRecentErrors(2);
+                const recentErrors = this.getRecentErrors(3);
                 recentErrors.forEach((err, idx) => {
                     console.log(chalk.red(`    ${idx + 1}. ${err.message}`));
+                    if (err.hint) {
+                        console.log(chalk.yellow(`       ${err.hint}`));
+                    }
                 });
 
-                if (summary.errors > 2) {
-                    console.log(chalk.gray(`    ... and ${summary.errors - 2} more`));
+                if (summary.errors > 3) {
+                    console.log(chalk.gray(`    ... and ${summary.errors - 3} more`));
                 }
             }