@genexus/mercury 1.0.0-beta.0 → 1.0.0-beta.1

package/dist/cli/migrate-mercury-tokens.js

@@ -1,102 +1,90 @@
 #!/usr/bin/env node
+// TODO: Add tests for this script.
+// TODO: remove following lines, and fix TS errors.
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-nocheck
 /**
  * Mercury Design System Token Migration Script
- * Version: 1.0.0
+ * Version: 2.0.0
  *
  * USAGE:
- * Run from your project root: bunx mercury update
+ * Run from your project root: npx mercury update
+ * Rollback changes: npx mercury update --rollback
  *
  * The script will:
- * - Find all CSS, SCSS, JS, TS, JSX, TSX files
- * - Replace old Mercury tokens with new V1 tokens
+ * - Preview all changes (dry-run by default)
+ * - Track primitive tokens (no modifications)
+ * - Ask for confirmation before applying
  * - Create backups in ./mercury-migration-backup/ folder
- * - Show you a report of what was changed
+ * - Show you a detailed report of what was changed
  */
 import fs from "fs";
 import path from "path";
 import { createInterface } from "readline";
+import { migrationToV1Metadata } from "../tokens/migrations/v1.js";
+const MERCURY_PREVIEW_REPORT_FILENAME = "mercury-migration-preview.txt";
+const MERCURY_BACKUP_DIRNAME = "mercury-migration-backup";
+const MIGRATION_REPORT_FILENAME = "migration-report.txt";
+const PRIMITIVE_TOKENS_REPORT_FILENAME = "mercury-primitive-report.txt";
+const UNDERLINE = "\x1b[4m";
+const COLORS = {
+    accentStart: [0, 204, 255], // var(--color-accent-gradient-start)
+    accentEnd: [207, 122, 255], // var(--color-accent-gradient-end)
+    statusWarning: [249, 189, 86], // var(--color-text-status-warning)
+    statusError: [227, 88, 97] // var(--color-text-status-error)
+};
+const reset = "\x1b[0m";
+const colorText = (text, rgb) => `\x1b[38;2;${rgb[0]};${rgb[1]};${rgb[2]}m${text}\x1b[0m`;
+const BULLET = "-";
+// Function to generate a gradient line by type
+function gradientLine() {
+    const length = 80;
+    const char = "/";
+    let line = "";
+    for (let i = 0; i < length; i++) {
+        const t = i / (length - 1); // normalized 0 → 1
+        const r = Math.round(COLORS.accentStart[0] + t * (COLORS.accentEnd[0] - COLORS.accentStart[0]));
+        const g = Math.round(COLORS.accentStart[1] + t * (COLORS.accentEnd[1] - COLORS.accentStart[1]));
+        const b = Math.round(COLORS.accentStart[2] + t * (COLORS.accentEnd[2] - COLORS.accentStart[2]));
+        line += `\x1b[38;2;${r};${g};${b}m${char}`;
+    }
+    return line + reset;
+}
 // ============================================================================
-// TOKEN MAPPINGS
+// TOKEN MAPPINGS - Built from metadata.ts
 // ============================================================================
-const TOKEN_MIGRATIONS = {
-    // Accent tokens
-    "--mer-accent__primary": "--color-accent-primary-default",
-    "--mer-accent__primary--hover": "--color-accent-primary-hover",
-    "--mer-accent__primary--active": "--color-accent-primary-pressed",
-    "--mer-accent__primary--disabled": "--color-accent-neutral-disabled",
-    "--mer-accent__primary--destructive": "--color-accent-error-default",
-    "--mer-accent__primary--destructive-hover": "--color-accent-error-hover",
-    "--mer-accent__primary--destructive-active": "--color-accent-error-pressed",
-    "--accent-success-lighter": "--color-accent-success-lighter",
-    "--accent-success-light": "--color-accent-success-light",
-    "--accent-success-enabled": "--color-accent-success-default",
-    "--accent-success-hover": "--color-accent-success-hover",
-    "--accent-success-active": "--color-accent-success-pressed",
-    // Border tokens
-    "--mer-border-color__primary": "--color-border-primary-default",
-    "--mer-border-color__primary--hover": "--color-border-primary-hover",
-    "--mer-border-color__primary--active": "--color-border-primary-pressed",
-    "--mer-border-color__primary--disabled": "--color-border-neutral-default",
-    "--mer-border-color__primary--focused": "--color-border-primary-focused",
-    "--mer-border-color__dim": "--color-border-neutral-default",
-    "--mer-border-color__neutral": "--color-border-neutral-light",
-    "--mer-border-color__neutral--hover": "--color-border-neutral-hover",
-    "--mer-border-color__neutral--active": "--color-border-neutral-pressed",
-    "--mer-border-color__error": "--color-border-error-default",
-    "--mer-border-color__error--hover": "--color-border-error-hover",
-    "--mer-border-color__error--active": "--color-border-error-pressed",
-    "--mer-border-color__warning": "--color-border-warning-default",
-    "--mer-border-color__success": "--color-border-success-default",
-    "--mer-border-color__on-surface": "--color-border-surface-on-elevation-01",
-    "--mer-border-color__on-elevation--01": "--color-border-surface-on-elevation-01",
-    "--mer-border-color__on-elevation--02": "--color-border-surface-on-elevation-02",
-    "--mer-border-color__on-elevation--03": "--color-border-surface-on-elevation-03",
-    // Icon tokens
-    "--mer-icon__on-surface": "--color-icon-neutral-default",
-    "--mer-icon__on-primary": "--color-icon-neutral-on-icon",
-    "--mer-icon__on-primary--hover": "--color-icon-primary-hover",
-    "--mer-icon__on-primary--active": "--color-icon-neutral-pressed",
-    "--mer-icon__on-disabled": "--color-icon-neutral-on-disabled",
-    "--mer-icon__on-message": "--color-icon-neutral-on-icon",
-    "--mer-icon__on-elevation": "--color-icon-neutral-default",
-    "--mer-icon__primary": "--color-icon-primary-default",
-    "--mer-icon__primary--hover": "--color-icon-primary-hover",
-    "--mer-icon__primary--active": "--color-icon-primary-pressed",
-    "--mer-icon__primary--disabled": "--color-icon-neutral-disabled",
-    "--mer-icon__error": "--color-icon-status-error",
-    "--mer-icon__warning": "--color-icon-status-warning",
-    "--mer-icon__success": "--color-icon-status-success",
-    "--mer-icon__neutral": "--color-icon-neutral-hover",
-    "--mer-icon__highlighted": "--color-icon-neutral-white",
-    "--mer-icon__bright": "--color-icon-neutral-hover",
-    // Surface tokens
-    "--mer-surface": "--color-accent-surface-surface",
-    "--mer-color__surface": "--color-text-neutral-default",
-    "--mer-surface__elevation--01": "--color-accent-surface-elevation-01",
-    "--mer-surface__elevation--02": "--color-accent-surface-elevation-02",
-    "--mer-surface__elevation--03": "--color-accent-surface-elevation-03",
-    "--mer-box-shadow--01": "--color-accent-shadow-shadow",
-    // Text tokens
-    "--mer-text__on-surface": "--color-text-neutral-default",
-    "--mer-text__on-primary": "--color-text-neutral-on-text",
-    "--mer-text__on-primary--active": "--color-text-neutral-on-pressed",
-    "--mer-text__on-disabled": "--color-text-neutral-on-disabled",
-    "--mer-text__on-message": "--color-text-neutral-default",
-    "--mer-text__on-elevation": "--color-text-neutral-default",
-    "--mer-text__primary": "--color-text-primary-default",
-    "--mer-text__primary--hover": "--color-text-primary-hover",
-    "--mer-text__primary--active": "--color-text-primary-pressed",
-    "--mer-text__primary--disabled": "--color-text-neutral-disabled",
-    "--mer-text__neutral": "--color-text-neutral-light",
-    "--mer-text__highlighted": "--color-text-neutral-white",
-    "--mer-text__complementary": "--color-text-neutral-disabled",
-    "--mer-text__bright": "--color-text-neutral-white",
-    "--mer-text__success": "--color-text-status-success",
-    "--mer-text__error": "--color-text-status-error",
-    "--mer-text__warning": "--color-text-status-warning"
-};
+/**
+ * Build token migrations object from metadata
+ * Iterates through all sections and subsections to extract before/after mappings
+ */
+function buildTokenMigrationsFromMetadata() {
+    const tokenMigrations = {};
+    migrationToV1Metadata.sections.forEach(section => {
+        // Handle sections with subsections
+        if (section.subsections) {
+            section.subsections.forEach(subsection => {
+                if (subsection.table) {
+                    subsection.table.forEach(row => {
+                        tokenMigrations[row.before] = row.after;
+                    });
+                }
+            });
+        }
+        // Handle sections with direct table (no subsections)
+        else if (section.table) {
+            section.table.forEach(row => {
+                tokenMigrations[row.before] = row.after;
+            });
+        }
+    });
+    return tokenMigrations;
+}
+// Build the migrations from metadata - this is now the source of truth
+const TOKEN_MIGRATIONS = buildTokenMigrationsFromMetadata();
+// Get primitive tokens from metadata
+const PRIMITIVE_TOKENS = migrationToV1Metadata.legacyPrimitiveTokens || [];
+console.log(`\n📋 Loaded ${Object.keys(TOKEN_MIGRATIONS).length} token migrations from metadata`);
+console.log(`📋 Loaded ${PRIMITIVE_TOKENS.length} primitive tokens to track`);
 // ============================================================================
 // CONFIGURATION
 // ============================================================================
@@ -127,15 +115,20 @@ const EXCLUDE_DIRS = [
     "public",
     "static",
     "vendor",
-    "mercury-migration-backup"
+    "www",
+    MERCURY_BACKUP_DIRNAME
 ];
 const stats = {
     filesProcessed: 0,
     filesModified: 0,
     tokensReplaced: 0,
-    replacements: {}
+    replacements: {},
+    primitiveTokens: {
+        totalFound: 0,
+        byFile: {} // { filePath: { token: count } }
+    }
 };
-const BACKUP_DIR = path.join(process.cwd(), "mercury-migration-backup");
+const BACKUP_DIR = path.join(process.cwd(), MERCURY_BACKUP_DIRNAME);
 // ============================================================================
 // HELPER FUNCTIONS
 // ============================================================================
@@ -167,6 +160,8 @@ function escapeRegex(string) {
 function replaceTokensInContent(content, filePath) {
     let modifiedContent = content;
     let fileModified = false;
+    const fileReplacements = {}; // Track replacements per file
+    const filePrimitiveTokens = {}; // Track primitive tokens per file
     // Sort tokens by length (longest first) to avoid partial replacements
     const sortedTokens = Object.keys(TOKEN_MIGRATIONS).sort((a, b) => b.length - a.length);
     sortedTokens.forEach(oldToken => {
@@ -178,6 +173,7 @@ function replaceTokensInContent(content, filePath) {
             fileModified = true;
             const count = matches.length;
             stats.tokensReplaced += count;
+            // Track for global stats
             if (!stats.replacements[oldToken]) {
                 stats.replacements[oldToken] = { count: 0, files: [] };
             }
@@ -185,10 +181,36 @@ function replaceTokensInContent(content, filePath) {
             if (!stats.replacements[oldToken].files.includes(filePath)) {
                 stats.replacements[oldToken].files.push(filePath);
             }
+            // Track for this specific file
+            fileReplacements[oldToken] = {
+                newToken,
+                count
+            };
             modifiedContent = modifiedContent.replace(varPattern, `var(${newToken}$1`);
         }
     });
-    return { modifiedContent, fileModified };
+    // Check for primitive tokens (no modifications, just tracking)
+    PRIMITIVE_TOKENS.forEach(primitiveToken => {
+        const varPattern = new RegExp(`var\\(${escapeRegex(primitiveToken)}([,)])`, "g");
+        const matches = content.match(varPattern);
+        if (matches) {
+            const count = matches.length;
+            stats.primitiveTokens.totalFound += count;
+            // Track for this specific file
+            filePrimitiveTokens[primitiveToken] = count;
+            // Track globally by file
+            if (!stats.primitiveTokens.byFile[filePath]) {
+                stats.primitiveTokens.byFile[filePath] = {};
+            }
+            stats.primitiveTokens.byFile[filePath][primitiveToken] = count;
+        }
+    });
+    return {
+        modifiedContent,
+        fileModified,
+        fileReplacements,
+        filePrimitiveTokens
+    };
 }
 function createBackup(filePath) {
     // Calculate relative path from cwd
@@ -202,167 +224,390 @@ function createBackup(filePath) {
     // Copy file to backup location
     fs.copyFileSync(filePath, backupPath);
 }
-function processFile(filePath) {
+function analyzeFile(filePath) {
     try {
         const content = fs.readFileSync(filePath, "utf8");
-        const { modifiedContent, fileModified } = replaceTokensInContent(content, filePath);
+        const { modifiedContent, fileModified, fileReplacements, filePrimitiveTokens } = replaceTokensInContent(content, filePath);
         stats.filesProcessed++;
-        if (fileModified) {
-            // Create backup in centralized folder
-            createBackup(filePath);
-            // Write modified content
-            fs.writeFileSync(filePath, modifiedContent, "utf8");
-            stats.filesModified++;
-            console.log(`✓ ${path.relative(process.cwd(), filePath)}`);
-        }
+        return {
+            modifiedContent,
+            fileModified,
+            fileReplacements,
+            filePrimitiveTokens
+        };
     }
     catch (error) {
         console.error(`✗ Error: ${path.relative(process.cwd(), filePath)} - ${error.message}`);
+        return {
+            modifiedContent: null,
+            fileModified: false,
+            fileReplacements: {},
+            filePrimitiveTokens: {}
+        };
     }
 }
-function generateReport() {
-    console.log("\n" + "═".repeat(80));
-    console.log("📊 MIGRATION REPORT");
-    console.log("═".repeat(80));
-    console.log(`Files processed: ${stats.filesProcessed}`);
-    console.log(`Files modified: ${stats.filesModified}`);
-    console.log(`Total tokens replaced: ${stats.tokensReplaced}`);
-    if (Object.keys(stats.replacements).length > 0) {
-        console.log("\n" + "─".repeat(80));
-        console.log("TOP TOKEN REPLACEMENTS:");
-        console.log("─".repeat(80));
-        Object.keys(stats.replacements)
-            .sort((a, b) => stats.replacements[b].count - stats.replacements[a].count)
-            .slice(0, 10)
-            .forEach(oldToken => {
-            const data = stats.replacements[oldToken];
-            console.log(`\n${oldToken}`);
-            console.log(`  → ${TOKEN_MIGRATIONS[oldToken]}`);
-            console.log(`  ✓ ${data.count} replacement(s) in ${data.files.length} file(s)`);
+function applyChanges(filePath, modifiedContent) {
+    try {
+        // Create backup in centralized folder
+        createBackup(filePath);
+        // Write modified content
+        fs.writeFileSync(filePath, modifiedContent, "utf8");
+        stats.filesModified++;
+        console.log(`✔ ${path.relative(process.cwd(), filePath)}`);
+    }
+    catch (error) {
+        console.error(`✗ Error: ${path.relative(process.cwd(), filePath)} - ${error.message}`);
+    }
+}
+function generatePreviewReport(fileChanges) {
+    const reportPath = path.join(process.cwd(), MERCURY_PREVIEW_REPORT_FILENAME);
+    let reportContent = "Mercury Design System Token Migration - PREVIEW\n";
+    reportContent += "=".repeat(60) + "\n\n";
+    reportContent += `THIS IS A PREVIEW - No files have been modified yet\n\n`;
+    reportContent += `Generated: ${new Date().toISOString()}\n\n`;
+    reportContent += "=".repeat(60) + "\n\n";
+    reportContent += `SUMMARY\n\n`;
+    reportContent += `Total tokens to replace: ${stats.tokensReplaced}\n`;
+    reportContent += `Total files to modify: ${fileChanges.size}\n\n`;
+    reportContent += "=".repeat(60) + "\n\n";
+    reportContent += `CHANGES BY FILE\n\n`;
+    // Sort files alphabetically for better readability
+    const sortedFiles = Array.from(fileChanges.keys()).sort();
+    sortedFiles.forEach(filePath => {
+        const relativePath = path.relative(process.cwd(), filePath);
+        const { fileReplacements } = fileChanges.get(filePath);
+        reportContent += `${relativePath}\n`;
+        // Sort tokens alphabetically within each file
+        const sortedTokens = Object.keys(fileReplacements).sort();
+        sortedTokens.forEach(oldToken => {
+            const info = fileReplacements[oldToken];
+            const occurrenceText = info.count === 1 ? "occurrence" : "occurrences";
+            reportContent += `  * ${oldToken} → ${info.newToken} (${info.count} ${occurrenceText})\n`;
+        });
+        reportContent += "\n";
+    });
+    reportContent += "=".repeat(60) + "\n";
+    fs.writeFileSync(reportPath, reportContent, "utf8");
+    return reportPath;
+}
+function generatePrimitiveTokensReport() {
+    const reportPath = path.join(process.cwd(), PRIMITIVE_TOKENS_REPORT_FILENAME);
+    let reportContent = "Mercury Design System Token Migration - PRIMITIVE TOKENS REPORT\n";
+    reportContent += "=".repeat(60) + "\n\n";
+    reportContent += `THIS IS A REPORT - No files will be modified\n\n`;
+    reportContent += `Generated: ${new Date().toISOString()}\n\n`;
+    reportContent += "=".repeat(60) + "\n\n";
+    reportContent += `SUMMARY\n\n`;
+    reportContent += `Total primitive tokens found: ${stats.primitiveTokens.totalFound}\n`;
+    reportContent += `No tokens will be modified\n\n`;
+    reportContent += "=".repeat(60) + "\n\n";
+    // Only generate the report if there are primitive tokens found
+    if (stats.primitiveTokens.totalFound > 0) {
+        reportContent += `PRIMITIVE TOKENS BY FILE\n\n`;
+        // Sort files alphabetically
+        const sortedFiles = Object.keys(stats.primitiveTokens.byFile).sort();
+        sortedFiles.forEach(filePath => {
+            const relativePath = path.relative(process.cwd(), filePath);
+            const tokens = stats.primitiveTokens.byFile[filePath];
+            reportContent += `${relativePath}\n`;
+            // Sort tokens alphabetically within each file
+            const sortedTokens = Object.keys(tokens).sort();
+            sortedTokens.forEach(token => {
+                const count = tokens[token];
+                const occurrenceText = count === 1 ? "occurrence" : "occurrences";
+                reportContent += `  * ${token} (${count} ${occurrenceText})\n`;
+            });
+            reportContent += "\n";
         });
+        reportContent += "=".repeat(60) + "\n";
     }
-    console.log("\n" + "═".repeat(80));
-    // Save detailed report inside backup folder
-    const reportPath = path.join(BACKUP_DIR, "_migration-report.txt");
-    const reportContent = `Mercury Design System Token Migration Report
-Generated: ${new Date().toISOString()}
-
-Summary:
---------
-Files processed: ${stats.filesProcessed}
-Files modified: ${stats.filesModified}
-Total tokens replaced: ${stats.tokensReplaced}
-
-Detailed Replacements:
----------------------
-${Object.keys(stats.replacements)
-        .sort((a, b) => stats.replacements[b].count - stats.replacements[a].count)
-        .map(oldToken => {
+    fs.writeFileSync(reportPath, reportContent, "utf8");
+    return reportPath;
+}
+function generateFinalReport() {
+    console.log("\n" + gradientLine() + "\n");
+    console.log(`${colorText(`${BULLET} Files processed:`, COLORS.accentStart)} ${stats.filesProcessed}`);
+    console.log(`${colorText(`${BULLET} Files modified:`, COLORS.accentStart)} ${stats.filesModified}`);
+    console.log(`${colorText(`${BULLET} Total tokens replaced:`, COLORS.accentStart)} ${stats.tokensReplaced}`);
+    // Save detailed report inside backup folder as txt
+    const reportPath = path.join(BACKUP_DIR, MIGRATION_REPORT_FILENAME);
+    let reportContent = "Mercury Design System Token Migration Report\n";
+    reportContent += "=".repeat(60) + "\n\n";
+    reportContent += `Generated: ${new Date().toISOString()}\n\n`;
+    reportContent += "=".repeat(60) + "\n\n";
+    reportContent += `SUMMARY\n\n`;
+    reportContent += `Files processed: ${stats.filesProcessed}\n`;
+    reportContent += `Files modified: ${stats.filesModified}\n`;
+    reportContent += `Total tokens replaced: ${stats.tokensReplaced}\n\n`;
+    reportContent += "=".repeat(60) + "\n\n";
+    reportContent += `CHANGES BY FILE\n\n`;
+    // Build a file-centric view from stats.replacements
+    const fileMap = new Map();
+    // Reorganize data by file
+    Object.keys(stats.replacements).forEach(oldToken => {
         const data = stats.replacements[oldToken];
-        return `\n${oldToken} → ${TOKEN_MIGRATIONS[oldToken]}\n  Replaced ${data.count} time(s) in ${data.files.length} file(s)\n  Files:\n${data.files.map(f => `    - ${path.relative(process.cwd(), f)}`).join("\n")}`;
-    })
-        .join("\n")}
-`;
+        const newToken = TOKEN_MIGRATIONS[oldToken];
+        data.files.forEach(filePath => {
+            if (!fileMap.has(filePath)) {
+                fileMap.set(filePath, []);
+            }
+            fileMap.get(filePath).push({
+                oldToken,
+                newToken
+                // Note: we don't have per-file counts in stats.replacements
+                // so we'll just show that it was replaced
+            });
+        });
+    });
+    // Sort files alphabetically
+    const sortedFiles = Array.from(fileMap.keys()).sort();
+    sortedFiles.forEach(filePath => {
+        const relativePath = path.relative(process.cwd(), filePath);
+        const tokens = fileMap.get(filePath);
+        reportContent += `${relativePath}\n`;
+        // Sort tokens alphabetically
+        tokens.sort((a, b) => a.oldToken.localeCompare(b.oldToken));
+        tokens.forEach(({ oldToken, newToken }) => {
+            reportContent += `  * ${oldToken} → ${newToken}\n`;
+        });
+        reportContent += "\n";
+    });
+    reportContent += "=".repeat(60) + "\n";
     fs.writeFileSync(reportPath, reportContent, "utf8");
-    console.log(`\n📄 Detailed report saved: ${path.relative(process.cwd(), reportPath)}`);
+}
+function displayPreviewSummary(fileCount) {
+    console.log(`${BULLET} Total tokens to replace: ${stats.tokensReplaced}`);
+    console.log(`${BULLET} Total files to modify: ${fileCount}`);
 }
 // ============================================================================
-// MAIN FUNCTION
+// ROLLBACK FUNCTION
+// ============================================================================
+function rollbackFromBackup() {
+    console.log("\n🔄 Rolling back changes from backup...\n");
+    if (!fs.existsSync(BACKUP_DIR)) {
+        console.error(`❌ Error: No backup found at ./${MERCURY_BACKUP_DIRNAME}/`);
+        console.log("💡 Nothing to rollback. Run migration first with: npx mercury update");
+        process.exit(1);
+    }
+    const readline = createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    readline.question("⚠️  This will restore all files from the backup. Continue? [y/N]: ", answer => {
+        if (answer.toLowerCase() === "y" || answer.toLowerCase() === "yes") {
+            console.log("\n📦 Restoring files...\n");
+            let filesRestored = 0;
+            function restoreFiles(backupPath) {
+                const items = fs.readdirSync(backupPath);
+                items.forEach(item => {
+                    const backupItemPath = path.join(backupPath, item);
+                    const relativePath = path.relative(BACKUP_DIR, backupItemPath);
+                    const originalPath = path.join(process.cwd(), relativePath);
+                    if (fs.statSync(backupItemPath).isDirectory()) {
+                        restoreFiles(backupItemPath);
+                    }
+                    else if (item !== MIGRATION_REPORT_FILENAME) {
+                        // Skip the report file
+                        fs.copyFileSync(backupItemPath, originalPath);
+                        filesRestored++;
+                        console.log(`✔ ${relativePath}`);
+                    }
+                });
+            }
+            restoreFiles(BACKUP_DIR);
+            console.log(`\n✅ Rollback complete! Restored ${filesRestored} file(s)`);
+            // Remove the backup folder after successful rollback
+            console.log("\n🗑️  Removing backup folder...");
+            fs.rmSync(BACKUP_DIR, { recursive: true, force: true });
+            console.log("\n✔ Backup folder removed");
+        }
+        else {
+            console.log("\n🚨 Rollback cancelled.");
+        }
+        readline.close();
+    });
+}
 // ============================================================================
+// HEADER PRINTING FUNCTION
+// ============================================================================
+function lerp(a, b, t) {
+    return Math.round(a + (b - a) * t);
+}
+function gradientText(text, startColor, endColor) {
+    const [r1, g1, b1] = startColor;
+    const [r2, g2, b2] = endColor;
+    let result = "";
+    for (let i = 0; i < text.length; i++) {
+        const t = i / (text.length - 1);
+        const r = lerp(r1, r2, t);
+        const g = lerp(g1, g2, t);
+        const b = lerp(b1, b2, t);
+        result += `\x1b[38;2;${r};${g};${b}m${text[i]}`;
+    }
+    // Reset color at the end
+    return result + "\x1b[0m";
+}
 function printHeader() {
-    // Blue gradient colors (from light to dark blue)
-    const colors = [
-        "\x1b[38;2;91;167;255m", // Lightest blue (#5ba7ff)
-        "\x1b[38;2;84;152;232m", // Light blue (#5498e8)
-        "\x1b[38;2;67;125;192m", // Mercury blue (#437dc0)
-        "\x1b[38;2;51;88;132m" // Dark blue (#335884)
-    ];
-    const reset = "\x1b[0m";
     const asciiLines = [
-        "    __  ___                                _    ____ ",
-        "   /  |/  /__  ____________  _________  __| |  / /_ |",
-        "  / /|_/ / _ \\/ ___/ ___/ / / / ___/ / / / | / / / /",
-        " / /  / /  __/ /  / /__/ /_/ / /  / /_/ /| |/ / / / ",
-        "/_/  /_/\\___/_/   \\___/\\__,_/_/   \\__, / |___/_/_/  ",
-        "                                  /____/             ",
-        "   Token Migration Tool"
+        "  __  __                                  _____     _                    __  __ _                 _             ",
+        " |  \\/  | ___ _ __ ___ _   _ _ __ _   _  |_   _|__ | | _____ _ __  ___  |  \\/  (_) __ _ _ __ __ _| |_ ___  _ __ ",
+        " | |\\/| |/ _ \\ '__/ __| | | | '__| | | |   | |/ _ \\| |/ / _ \\ '_ \\/ __| | |\\/| | |/ _` | '__/ _` | __/ _ \\| '__|",
+        " | |  | |  __/ | | (__| |_| | |  | |_| |   | | (_) |   <  __/ | | \\__ \\ | |  | | | (_| | | | (_| | || (_) | |   ",
+        " |_|  |_|\\___|_|  \\___|\\__,_|_|   \\__, |   |_|\\___/|_|\\_\\___|_| |_|___/ |_|  |_|_|\\__, |_|  \\__,_|\\__\\___/|_|   ",
+        "                                  |___/                                           |___/                          ",
+        ""
     ];
     console.log("");
-    asciiLines.forEach((line, index) => {
-        const colorIndex = Math.min(Math.floor(index / 2), colors.length - 1);
-        console.log(colors[colorIndex] + line + reset);
-    });
+    asciiLines.forEach(line => console.log(gradientText(line, COLORS.accentStart, COLORS.accentEnd)));
     console.log("");
 }
+// ============================================================================
+// MAIN FUNCTION
+// ============================================================================
 export function migrateMercuryTokens() {
     printHeader();
-    console.log("═".repeat(80));
+    console.log(gradientLine());
     // Handle command parsing
     const args = process.argv.slice(2);
-    const command = args[0];
-    // If first arg is "update", use current directory
-    // Otherwise treat first arg as the target directory
-    let targetDir;
-    if (command === "update") {
-        targetDir = args[1] || process.cwd();
-    }
-    else {
-        targetDir = command || process.cwd();
+    const hasRollback = args.includes("--rollback");
+    // Handle rollback
+    if (hasRollback) {
+        rollbackFromBackup();
+        return;
     }
+    // Determine target directory
+    // Filter out "update" command if present, as it's the default command
+    const filteredArgs = args.filter(arg => arg !== "update");
+    const targetDir = filteredArgs[0] || process.cwd();
     if (!fs.existsSync(targetDir)) {
         console.error(`\n❌ Error: Directory "${targetDir}" does not exist`);
         process.exit(1);
     }
-    console.log(`\n📁 Target: ${targetDir}`);
-    console.log(`📝 File types: ${FILE_EXTENSIONS.join(", ")}`);
-    console.log(`🚫 Excluding: ${EXCLUDE_DIRS.join(", ")}`);
-    console.log("\n⏳ Scanning files...");
+    console.log(`\n${colorText(`${BULLET} Target:`, COLORS.accentStart)} ${targetDir}`);
+    console.log(`${colorText(`${BULLET} File types:`, COLORS.accentStart)} ${FILE_EXTENSIONS.join(", ")}`);
+    console.log(`${colorText(`${BULLET} Excluding:`, COLORS.accentStart)} ${EXCLUDE_DIRS.join(", ")}`);
+    console.log(`${colorText(`Scanning files...`, COLORS.accentEnd)}`);
     const files = getAllFiles(targetDir);
-    console.log(`\n✓ Found ${files.length} file(s) to process`);
+    console.log(`\n✔ Found ${files.length} file(s) to scan`);
     if (files.length === 0) {
         console.log("\n⚠️  No files found to migrate. Exiting.");
         process.exit(0);
     }
-    // Confirmation prompt
+    // Phase 1: DRY RUN - Analyze all files
+    console.log("\n" + gradientLine() + "\n");
+    console.log("PHASE 1: Preview Changes (Dry-Run)");
+    console.log("\n⳿ Analyzing files (No changes will be applied at this stage)...");
+    const fileChanges = new Map();
+    let processedCount = 0;
+    files.forEach(file => {
+        const { modifiedContent, fileModified, fileReplacements } = analyzeFile(file);
+        if (fileModified) {
+            fileChanges.set(file, { modifiedContent, fileReplacements });
+        }
+        // Show progress indicator
+        processedCount++;
+        if (processedCount % 10 === 0 || processedCount === files.length) {
+            process.stdout.write(`\r⳿ Analyzing: ${processedCount}/${files.length} files...`);
+        }
+    });
+    // Clear the progress line
+    process.stdout.write("\r" + " ".repeat(60) + "\r");
+    if (fileChanges.size === 0) {
+        console.log("\n✔ No changes needed - all tokens are up to date!");
+        process.exit(0);
+    }
+    // Display preview summary
+    displayPreviewSummary(fileChanges.size);
+    // Generate preview report
+    const previewReportPath = generatePreviewReport(fileChanges);
+    // Generate primitive tokens report silently if any were found
+    let primitiveReportPath = null;
+    if (stats.primitiveTokens.totalFound > 0) {
+        primitiveReportPath = generatePrimitiveTokensReport();
+    }
+    console.log(`\n📄 A preview of the proposed changes has been saved: ${UNDERLINE}${colorText(path.relative(process.cwd(), previewReportPath), COLORS.accentStart)}${reset}`);
+    console.log(`👉 Next steps:`);
+    console.log(`- 1. Review the preview report to see what will change`);
+    console.log(`- 2. Answer the prompt below to continue or cancel`);
+    // Phase 2: Confirmation
     const readline = createInterface({
         input: process.stdin,
         output: process.stdout
     });
-    readline.question("\n⚠️  Continue? Backups will be saved to ./mercury-migration-backup/ [y/N]: ", answer => {
+    const applyChangesPrompt = `\n⚠️  Apply these changes? Backups will be saved to ./${MERCURY_BACKUP_DIRNAME}/ [y/N]: `;
+    readline.question(colorText(applyChangesPrompt, COLORS.statusWarning), answer => {
         if (answer.toLowerCase() === "y" || answer.toLowerCase() === "yes") {
-            console.log("\n🔄 Processing...\n");
+            // Phase 3: Apply changes
+            console.log("\n" + gradientLine() + "\n");
+            console.log("PHASE 2: Applying Changes");
+            console.log("\n⳿ Creating backups and applying changes...\n");
             // Create backup directory
             if (!fs.existsSync(BACKUP_DIR)) {
                 fs.mkdirSync(BACKUP_DIR, { recursive: true });
             }
-            files.forEach(file => processFile(file));
-            generateReport();
-            if (stats.filesModified > 0) {
-                console.log("\n✅ Migration complete!");
-                const reportPath = path.join(BACKUP_DIR, "_migration-report.txt");
-                const reportRelPath = path.relative(process.cwd(), reportPath);
-                const reportAbsPath = path.resolve(reportPath);
-                // ANSI color code for #437DC0 (RGB: 67, 125, 192)
-                const blueColor = "\x1b[38;2;67;125;192m";
-                const resetColor = "\x1b[0m";
-                // VS Code URL scheme for opening file directly in editor (degrades gracefully)
-                const reportLink = `${blueColor}\x1b]8;;vscode://file/${reportAbsPath}\x1b\\${reportRelPath}\x1b]8;;\x1b\\${resetColor}`;
-                console.log("\n💡 Next steps:");
-                console.log("   1. 📊 Open the migration report to see all changes:");
-                console.log(`      → ${reportLink}`);
-                console.log("      (Contains detailed list of every token replaced in every file)");
-                console.log("   2. Test your application thoroughly");
-                console.log(`   3. Original files backed up in: ${path.relative(process.cwd(), BACKUP_DIR)}/`);
-                console.log("   4. When everything works, delete the backup:");
-                console.log("      rm -rf mercury-migration-backup");
+            // Reset stats for final count
+            stats.filesModified = 0;
+            // Apply all changes
+            fileChanges.forEach((data, filePath) => {
+                applyChanges(filePath, data.modifiedContent);
+            });
+            generateFinalReport();
+            console.log("\n✅ Migration complete!");
+            const reportPath = path.join(BACKUP_DIR, MIGRATION_REPORT_FILENAME);
+            const reportRelPath = path.relative(process.cwd(), reportPath);
+            console.log("\n👉 Next steps:\n");
+            console.log(`1. Review the migration report: ${UNDERLINE}${colorText(reportRelPath, COLORS.accentStart)}${reset}\n`);
+            console.log("2. Test your application thoroughly\n");
+            // Only show primitive tokens step if they were found
+            if (stats.primitiveTokens.totalFound > 0) {
+                console.log(`3. Review the primitive color tokens report (${UNDERLINE}${colorText(PRIMITIVE_TOKENS_REPORT_FILENAME, COLORS.accentStart)}${reset}) and update them manually using the new semantic color tokens documented in the showcase (Core concepts → Tokens)\n`);
             }
-            else {
-                console.log("\n✓ No changes needed - all tokens are up to date!");
+            console.log(`4. ✓ When everything works, delete the backup: ${colorText(`rm -rf ${MERCURY_BACKUP_DIRNAME}`, COLORS.accentEnd)} (Backups saved in: ${UNDERLINE}${colorText(MERCURY_BACKUP_DIRNAME, COLORS.accentStart)}${reset})\n`);
+            console.log(`5. ↩ If needed, rollback with: ${colorText("npx mercury update --rollback", COLORS.accentEnd)}`);
+            // Delete preview report after successful migration
+            if (fs.existsSync(previewReportPath)) {
+                fs.unlinkSync(previewReportPath);
             }
+            // DO NOT delete primitive tokens report - user needs it for manual updates
+            readline.close();
         }
         else {
-            console.log("\n❌ Migration cancelled.");
+            const migrationCancelledPrompt = `\n🚨 Migration cancelled. No files were modified.`;
+            console.log(migrationCancelledPrompt);
+            // Ask if user wants to keep the reports
+            const previewReportPathText = path.relative(process.cwd(), previewReportPath);
+            // Build the prompt message based on whether primitive tokens were found
+            let keepReportsPrompt = `\n⚠️  Do you want to keep the reports (${MERCURY_PREVIEW_REPORT_FILENAME}`;
+            if (primitiveReportPath && stats.primitiveTokens.totalFound > 0) {
+                keepReportsPrompt += ` and ${PRIMITIVE_TOKENS_REPORT_FILENAME}`;
+            }
+            keepReportsPrompt += `)? [y/N]: `;
+            readline.question(colorText(keepReportsPrompt, COLORS.statusWarning), keepReports => {
+                if (keepReports.toLowerCase() === "y" ||
+                    keepReports.toLowerCase() === "yes") {
+                    console.log(`\n📄 Preview report saved at: ${UNDERLINE}${colorText(previewReportPathText, COLORS.accentStart)}${reset}`);
+                    if (primitiveReportPath && stats.primitiveTokens.totalFound > 0) {
+                        console.log(`📄 Primitive tokens report saved at: ${UNDERLINE}${colorText(path.relative(process.cwd(), primitiveReportPath), COLORS.accentStart)}${reset}`);
+                    }
+                    console.log("");
+                }
+                else {
+                    // Delete preview report
+                    if (fs.existsSync(previewReportPath)) {
+                        fs.unlinkSync(previewReportPath);
+                        console.log(`\n🗑️  ${MERCURY_PREVIEW_REPORT_FILENAME} was deleted`);
+                    }
+                    // Delete primitive tokens report if it exists
+                    if (primitiveReportPath &&
+                        fs.existsSync(primitiveReportPath) &&
+                        stats.primitiveTokens.totalFound > 0) {
+                        fs.unlinkSync(primitiveReportPath);
+                        console.log(`🗑️  ${PRIMITIVE_TOKENS_REPORT_FILENAME} was deleted`);
+                    }
+                    console.log("");
+                }
+                readline.close();
+            });
         }
-        readline.close();
     });
 }