filemayor 3.6.0 → 4.0.5

package/core/reporter.js

@@ -1,783 +1,783 @@
-#!/usr/bin/env node
-
-/**
- * ═══════════════════════════════════════════════════════════════════
- * FILEMAYOR CORE — REPORTER
- * Multi-format output (table, JSON, CSV, minimal) with colors,
- * summary statistics, and machine-readable formats for piping.
- * ═══════════════════════════════════════════════════════════════════
- */
-
-'use strict';
-
-const { formatBytes } = require('./scanner');
-
-// ─── ANSI Color Codes ─────────────────────────────────────────────
-
-const COLORS = {
-    reset: '\x1b[0m',
-    bold: '\x1b[1m',
-    dim: '\x1b[2m',
-    italic: '\x1b[3m',
-    underline: '\x1b[4m',
-
-    // Foreground
-    black: '\x1b[30m',
-    red: '\x1b[31m',
-    green: '\x1b[32m',
-    yellow: '\x1b[33m',
-    blue: '\x1b[34m',
-    magenta: '\x1b[35m',
-    cyan: '\x1b[36m',
-    white: '\x1b[37m',
-    gray: '\x1b[90m',
-
-    // Bright
-    brightRed: '\x1b[91m',
-    brightGreen: '\x1b[92m',
-    brightYellow: '\x1b[93m',
-    brightBlue: '\x1b[94m',
-    brightMagenta: '\x1b[95m',
-    brightCyan: '\x1b[96m',
-    brightWhite: '\x1b[97m',
-
-    // Background
-    bgRed: '\x1b[41m',
-    bgGreen: '\x1b[42m',
-    bgYellow: '\x1b[43m',
-    bgBlue: '\x1b[44m',
-    bgMagenta: '\x1b[45m',
-    bgCyan: '\x1b[46m',
-};
-
-let _colorsEnabled = true;
-
-function c(color, text) {
-    if (!_colorsEnabled) return text;
-    return `${COLORS[color]}${text}${COLORS.reset}`;
-}
-
-function setColors(enabled) {
-    _colorsEnabled = enabled;
-}
-
-// ─── Symbols ──────────────────────────────────────────────────────
-
-const SYMBOLS = {
-    check: '✓',
-    cross: '✗',
-    arrow: '→',
-    bullet: '•',
-    bar: '█',
-    halfBar: '▓',
-    lightBar: '░',
-    folder: '📂',
-    file: '📄',
-    trash: '🗑️',
-    sparkle: '✨',
-    warning: '⚠️',
-    error: '❌',
-    info: 'ℹ️',
-    clock: '⏱️',
-    shield: '🛡️',
-    eye: '👁️',
-};
-
-// ─── Table Formatter ──────────────────────────────────────────────
-
-/**
- * Format data as a table with aligned columns
- * @param {Object[]} data - Array of objects
- * @param {Object} options - Column config
- * @returns {string} Formatted table
- */
-function formatTable(data, options = {}) {
-    if (!data || data.length === 0) return c('dim', '  (no data)');
-
-    const {
-        columns = null,     // Column definitions [{key, label, width, align, format}]
-        maxWidth = null,    // Max column width
-        indent = 2,         // Left indent
-    } = options;
-
-    // Auto-detect columns from data
-    const cols = columns || Object.keys(data[0]).map(key => ({
-        key,
-        label: key.charAt(0).toUpperCase() + key.slice(1),
-        align: 'left'
-    }));
-
-    // Calculate column widths
-    for (const col of cols) {
-        if (!col.width) {
-            const maxDataLen = Math.max(
-                col.label.length,
-                ...data.map(row => {
-                    const val = col.format ? col.format(row[col.key], row) : String(row[col.key] ?? '');
-                    return val.length;
-                })
-            );
-            col.width = maxWidth ? Math.min(maxDataLen, maxWidth) : maxDataLen;
-        }
-    }
-
-    const lines = [];
-    const pad = ' '.repeat(indent);
-
-    // Header
-    const headerLine = cols.map(col => {
-        const label = col.label.padEnd(col.width).slice(0, col.width);
-        return c('bold', label);
-    }).join(c('dim', '  '));
-    lines.push(`${pad}${headerLine}`);
-
-    // Separator
-    const sep = cols.map(col => c('dim', '─'.repeat(col.width))).join(c('dim', '──'));
-    lines.push(`${pad}${sep}`);
-
-    // Rows
-    for (const row of data) {
-        const rowLine = cols.map(col => {
-            let val = col.format ? col.format(row[col.key], row) : String(row[col.key] ?? '');
-            const rawVal = val.replace(/\x1b\[[0-9;]*m/g, ''); // Strip ANSI for length calc
-
-            if (col.align === 'right') {
-                val = ' '.repeat(Math.max(0, col.width - rawVal.length)) + val;
-            } else {
-                val = val + ' '.repeat(Math.max(0, col.width - rawVal.length));
-            }
-            return val;
-        }).join('  ');
-        lines.push(`${pad}${rowLine}`);
-    }
-
-    return lines.join('\n');
-}
-
-// ─── Progress Bar ─────────────────────────────────────────────────
-
-/**
- * Render a progress bar string
- * @param {number} percent - 0-100
- * @param {number} width - Bar width in chars
- * @returns {string}
- */
-function progressBar(percent, width = 30) {
-    const clamped = Math.max(0, Math.min(100, percent || 0));
-    const filled = Math.round((clamped / 100) * width);
-    const empty = width - filled;
-    const bar = c('green', SYMBOLS.bar.repeat(filled)) +
-        c('dim', SYMBOLS.lightBar.repeat(empty));
-    return `${bar} ${c('bold', `${clamped}%`)}`;
-}
-
-// ─── Spinner ──────────────────────────────────────────────────────
-
-class Spinner {
-    constructor(message = 'Working...') {
-        this.message = message;
-        this.frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
-        this.frameIndex = 0;
-        this.interval = null;
-        this.stream = process.stderr;
-    }
-
-    start() {
-        this.interval = setInterval(() => {
-            const frame = c('cyan', this.frames[this.frameIndex]);
-            this.stream.write(`\r${frame} ${this.message}`);
-            this.frameIndex = (this.frameIndex + 1) % this.frames.length;
-        }, 80);
-        return this;
-    }
-
-    update(message) {
-        this.message = message;
-    }
-
-    succeed(message) {
-        this.stop();
-        this.stream.write(`\r${c('green', SYMBOLS.check)} ${message || this.message}\n`);
-    }
-
-    fail(message) {
-        this.stop();
-        this.stream.write(`\r${c('red', SYMBOLS.cross)} ${message || this.message}\n`);
-    }
-
-    stop() {
-        if (this.interval) {
-            clearInterval(this.interval);
-            this.interval = null;
-            this.stream.write('\r' + ' '.repeat(this.message.length + 10) + '\r');
-        }
-    }
-}
-
-// ─── Scan Report ──────────────────────────────────────────────────
-
-/**
- * Format a scan result for display
- * @param {Object} scanResult - Result from scan()
- * @param {string} format - Output format
- * @returns {string}
- */
-function formatScanReport(scanResult, format = 'table') {
-    switch (format) {
-        case 'json':
-            return JSON.stringify(scanResult, null, 2);
-
-        case 'csv':
-            return formatScanCSV(scanResult);
-
-        case 'minimal':
-            return scanResult.files.map(f => f.path).join('\n');
-
-        case 'table':
-        default:
-            return formatScanTable(scanResult);
-    }
-}
-
-function formatScanTable(result) {
-    const lines = [];
-
-    // Header
-    lines.push('');
-    lines.push(c('bold', `  ${SYMBOLS.folder} Scan Report: `) + c('cyan', result.root));
-    lines.push(c('dim', `  ${SYMBOLS.shield} Integrity Check: `) + c('green', 'PASSED'));
-    lines.push(c('dim', `  ${'─'.repeat(60)}`));
-
-    // Category summary
-    const catData = Object.entries(result.stats.categories)
-        .sort((a, b) => b[1] - a[1])
-        .map(([cat, count]) => ({
-            category: cat.charAt(0).toUpperCase() + cat.slice(1),
-            count: String(count),
-        }));
-
-    if (catData.length > 0) {
-        lines.push('');
-        lines.push(c('bold', '  Categories'));
-        lines.push(formatTable(catData, {
-            columns: [
-                { key: 'category', label: 'Category', width: 20 },
-                { key: 'count', label: 'Files', width: 8, align: 'right' },
-            ]
-        }));
-    }
-
-    // File list (top 25)
-    const fileData = result.files.slice(0, 25).map(f => ({
-        name: f.name.length > 40 ? f.name.slice(0, 37) + '...' : f.name,
-        category: f.category,
-        size: f.sizeHuman,
-    }));
-
-    if (fileData.length > 0) {
-        lines.push('');
-        lines.push(c('bold', '  Files'));
-        lines.push(formatTable(fileData, {
-            columns: [
-                { key: 'name', label: 'Name', width: 42 },
-                { key: 'category', label: 'Category', width: 14 },
-                { key: 'size', label: 'Size', width: 10, align: 'right' },
-            ]
-        }));
-
-        if (result.files.length > 25) {
-            lines.push(c('dim', `  ... and ${result.files.length - 25} more files`));
-        }
-    }
-
-    // Summary
-    lines.push('');
-    lines.push(c('dim', `  ${'─'.repeat(60)}`));
-    lines.push(`  ${c('bold', 'Total:')} ${result.stats.filesFound} files, ${formatBytes(result.stats.totalSize)}`);
-    lines.push(`  ${c('bold', 'Scanned:')} ${result.stats.dirsScanned} directories in ${result.stats.durationHuman}`);
-    if (result.stats.errors.length > 0) {
-        lines.push(`  ${c('yellow', SYMBOLS.warning)} ${result.stats.errors.length} errors`);
-    }
-    lines.push('');
-
-    return lines.join('\n');
-}
-
-function formatScanCSV(result) {
-    const header = 'name,path,category,size,modified,ext';
-    const rows = result.files.map(f =>
-        `"${f.name}","${f.path}","${f.category}",${f.size},"${f.modified.toISOString()}","${f.ext}"`
-    );
-    return [header, ...rows].join('\n');
-}
-
-// ─── Organize Report ──────────────────────────────────────────────
-
-function formatOrganizeReport(result, format = 'table') {
-    // Defensive: handle empty/incomplete results
-    if (!result || (!result.plan && !result.planSummary)) {
-        return `\n  ${c('green', SYMBOLS.check)} Nothing to organize — folder is already clean.\n`;
-    }
-    if (!result.plan) result.plan = [];
-    if (!result.planSummary) result.planSummary = { categories: {}, totalFiles: 0, totalSizeHuman: '0 B' };
-
-    switch (format) {
-        case 'json':
-            return JSON.stringify(result, null, 2);
-        case 'csv':
-            return formatOrganizeCSV(result);
-        case 'minimal':
-            return result.plan.map(p => `${p.source} ${SYMBOLS.arrow} ${p.destination}`).join('\n');
-        case 'table':
-        default:
-            return formatOrganizeTable(result);
-    }
-}
-
-function formatOrganizeTable(result) {
-    const lines = [];
-    const plan = result.plan;
-    const isDryRun = result.dryRun;
-
-    lines.push('');
-    if (isDryRun) {
-        lines.push(c('yellow', `  ${SYMBOLS.eye} DRY RUN — No files will be moved`));
-    } else {
-        lines.push(c('green', `  ${SYMBOLS.sparkle} Organization Complete`));
-    }
-    lines.push(c('dim', `  ${SYMBOLS.shield} Integrity Check: `) + c('green', 'PASSED'));
-    lines.push(c('dim', `  ${'─'.repeat(60)}`));
-
-    // Category breakdown
-    const catSummary = result.planSummary.categories;
-    const catData = Object.entries(catSummary)
-        .sort((a, b) => b[1].count - a[1].count)
-        .map(([cat, info]) => ({
-            category: cat,
-            files: String(info.count),
-            size: formatBytes(info.size)
-        }));
-
-    if (catData.length > 0) {
-        lines.push('');
-        lines.push(c('bold', '  Breakdown'));
-        lines.push(formatTable(catData, {
-            columns: [
-                { key: 'category', label: 'Category', width: 20 },
-                { key: 'files', label: 'Files', width: 8, align: 'right' },
-                { key: 'size', label: 'Size', width: 10, align: 'right' },
-            ]
-        }));
-    }
-
-    // Move preview (top 15)
-    const preview = plan.slice(0, 15).map(p => ({
-        from: p.originalName.length > 30 ? p.originalName.slice(0, 27) + '...' : p.originalName,
-        to: p.categoryLabel,
-        action: p.action === 'move' ? c('green', 'move') :
-            p.action === 'skip' ? c('yellow', 'skip') :
-                p.action === 'rename' ? c('cyan', 'rename') :
-                    c('red', p.action)
-    }));
-
-    if (preview.length > 0) {
-        lines.push('');
-        lines.push(c('bold', '  Operations'));
-        lines.push(formatTable(preview, {
-            columns: [
-                { key: 'from', label: 'File', width: 32 },
-                { key: 'to', label: 'Destination', width: 16 },
-                { key: 'action', label: 'Action', width: 10 },
-            ]
-        }));
-
-        if (plan.length > 15) {
-            lines.push(c('dim', `  ... and ${plan.length - 15} more operations`));
-        }
-    }
-
-    // Summary
-    lines.push('');
-    lines.push(c('dim', `  ${'─'.repeat(60)}`));
-    lines.push(`  ${c('bold', 'Total:')} ${result.planSummary.totalFiles} files, ${result.planSummary.totalSizeHuman}`);
-
-    if (!isDryRun && result.execSummary) {
-        const exec = result.execSummary;
-        lines.push(`  ${c('green', SYMBOLS.check)} ${exec.succeeded} succeeded`);
-        if (exec.failed > 0) lines.push(`  ${c('red', SYMBOLS.cross)} ${exec.failed} failed`);
-        if (exec.skipped > 0) lines.push(`  ${c('yellow', '⊘')} ${exec.skipped} skipped`);
-    } else if (isDryRun) {
-        lines.push(c('dim', `  Run without --dry-run to execute these changes`));
-    }
-
-    lines.push('');
-    return lines.join('\n');
-}
-
-function formatOrganizeCSV(result) {
-    const header = 'source,destination,category,original_name,new_name,size,action';
-    const rows = result.plan.map(p =>
-        `"${p.source}","${p.destination}","${p.category}","${p.originalName}","${p.newName}",${p.size},"${p.action}"`
-    );
-    return [header, ...rows].join('\n');
-}
-
-// ─── Clean Report ─────────────────────────────────────────────────
-
-function formatCleanReport(result, format = 'table') {
-    switch (format) {
-        case 'json':
-            return JSON.stringify(result, null, 2);
-        case 'csv':
-            return formatCleanCSV(result);
-        case 'minimal':
-            return result.junk.map(j => `${j.sizeHuman}\t${j.path}`).join('\n');
-        case 'table':
-        default:
-            return formatCleanTable(result);
-    }
-}
-
-function formatCleanTable(result) {
-    const lines = [];
-    const isDryRun = result.dryRun;
-
-    lines.push('');
-    if (isDryRun) {
-        lines.push(c('yellow', `  ${SYMBOLS.eye} DRY RUN — No files will be deleted`));
-    } else if (result.deleteResult) {
-        lines.push(c('green', `  ${SYMBOLS.trash} Cleanup Complete`));
-    } else {
-        lines.push(c('cyan', `  ${SYMBOLS.trash} Junk Scan Results`));
-    }
-    lines.push(c('dim', `  ${SYMBOLS.shield} Integrity Check: `) + c('green', 'PASSED'));
-    lines.push(c('dim', `  ${'─'.repeat(60)}`));
-
-    // Category breakdown
-    const byCategory = result.stats.byCategory;
-    const catData = Object.entries(byCategory)
-        .sort((a, b) => b[1].size - a[1].size)
-        .map(([cat, info]) => ({
-            category: cat.charAt(0).toUpperCase() + cat.slice(1),
-            items: String(info.count),
-            size: formatBytes(info.size)
-        }));
-
-    if (catData.length > 0) {
-        lines.push('');
-        lines.push(c('bold', '  Junk Categories'));
-        lines.push(formatTable(catData, {
-            columns: [
-                { key: 'category', label: 'Category', width: 20 },
-                { key: 'items', label: 'Items', width: 8, align: 'right' },
-                { key: 'size', label: 'Size', width: 10, align: 'right' },
-            ]
-        }));
-    }
-
-    // Largest items (top 10)
-    const sorted = [...result.junk].sort((a, b) => b.size - a.size).slice(0, 10);
-    const itemData = sorted.map(j => ({
-        name: j.name.length > 35 ? j.name.slice(0, 32) + '...' : j.name,
-        type: j.type === 'directory' ? c('blue', 'DIR') : c('dim', 'FILE'),
-        size: j.sizeHuman,
-    }));
-
-    if (itemData.length > 0) {
-        lines.push('');
-        lines.push(c('bold', '  Largest Junk Items'));
-        lines.push(formatTable(itemData, {
-            columns: [
-                { key: 'name', label: 'Name', width: 37 },
-                { key: 'type', label: 'Type', width: 6 },
-                { key: 'size', label: 'Size', width: 10, align: 'right' },
-            ]
-        }));
-    }
-
-    // Summary
-    lines.push('');
-    lines.push(c('dim', `  ${'─'.repeat(60)}`));
-    lines.push(`  ${c('bold', 'Total junk:')} ${result.stats.filesFound + result.stats.dirsFound} items, ${result.stats.totalSizeHuman}`);
-
-    if (result.deleteResult) {
-        const dr = result.deleteResult;
-        lines.push(`  ${c('green', SYMBOLS.check)} Deleted ${dr.deleted} items, freed ${dr.freedHuman}`);
-        if (dr.errors.length > 0) {
-            lines.push(`  ${c('red', SYMBOLS.cross)} ${dr.errors.length} errors`);
-        }
-    } else if (isDryRun) {
-        lines.push(c('dim', `  Run without --dry-run to clean these files`));
-    }
-
-    lines.push('');
-    return lines.join('\n');
-}
-
-function formatCleanCSV(result) {
-    const header = 'name,path,category,type,size';
-    const rows = result.junk.map(j =>
-        `"${j.name}","${j.path}","${j.category}","${j.type}",${j.size}`
-    );
-    return [header, ...rows].join('\n');
-}
-
-// ─── Generic Utilities ────────────────────────────────────────────
-
-/**
- * Print a header banner
- */
-function banner() {
-    return [
-        '',
-        c('bold', `  ${SYMBOLS.sparkle} FileMayor`) + c('dim', ' — Your Digital Life Organizer'),
-        c('dim', '  by Lehlohonolo Goodwill Nchefu (Chevza)'),
-        c('dim', `  ${'─'.repeat(50)}`),
-        ''
-    ].join('\n');
-}
-
-/**
- * Print a success message
- */
-function success(msg) {
-    return `${c('green', SYMBOLS.check)} ${msg}`;
-}
-
-/**
- * Print an error message
- */
-function error(msg) {
-    return `${c('red', SYMBOLS.cross)} ${msg}`;
-}
-
-/**
- * Print a warning message
- */
-function warn(msg) {
-    return `${c('yellow', SYMBOLS.warning)} ${msg}`;
-}
-
-/**
- * Print an info message
- */
-function info(msg) {
-    return `${c('cyan', SYMBOLS.info)} ${msg}`;
-}
-
-// ─── Analyze Report ────────────────────────────────────────────────
-
-function formatAnalyzeReport(result, format = 'table') {
-    if (format === 'json') return JSON.stringify(result, null, 2);
-
-    const lines = [];
-    lines.push('');
-    lines.push(c('bold', `  ${SYMBOLS.eye} Deep Intelligence Report: `) + c('cyan', result.root));
-    lines.push(c('dim', `  ${'─'.repeat(60)}`));
-
-    // Summary Insights
-    lines.push('');
-    lines.push(`  ${c('bold', 'Summary:')}   ${result.summary.totalFiles} files detected. Total size: ${result.summary.totalSizeHuman}`);
-    lines.push(`  ${c('green', '⚡ Insight:')}  You can reclaim ${c('bold', result.summary.potentialSavingsHuman)} today.`);
-
-    // Duplicates Section
-    if (result.duplicates.sets > 0) {
-        lines.push('');
-        lines.push(c('bold', '  Duplicate Bloat'));
-        const dupeData = result.duplicates.details.map(d => ({
-            name: d.files[0].name.length > 35 ? d.files[0].name.slice(0, 32) + '...' : d.files[0].name,
-            count: String(d.files.length),
-            wasted: d.wastedSpaceHuman
-        }));
-        lines.push(formatTable(dupeData, {
-            columns: [
-                { key: 'name', label: 'File Name', width: 37 },
-                { key: 'count', label: 'Copies', width: 8, align: 'right' },
-                { key: 'wasted', label: 'Wasted', width: 10, align: 'right' }
-            ]
-        }));
-        lines.push(`  ${c('dim', `  Found ${result.duplicates.sets} duplicate sets causing ${result.duplicates.totalWastedHuman} bloat.`)}`);
-    }
-
-    // Largest Folders Section
-    if (result.largestDirs.length > 0) {
-        lines.push('');
-        lines.push(c('bold', '  Top Space Consumers (Bloat Map)'));
-        const dirData = result.largestDirs.map(d => ({
-            name: d.name.length > 37 ? d.name.slice(0, 34) + '...' : d.name,
-            files: String(d.count),
-            size: d.sizeHuman
-        }));
-        lines.push(formatTable(dirData, {
-            columns: [
-                { key: 'name', label: 'Directory', width: 40 },
-                { key: 'files', label: 'Files', width: 8, align: 'right' },
-                { key: 'size', label: 'Size', width: 10, align: 'right' }
-            ]
-        }));
-    }
-
-    // Junk Section
-    if (result.junk.count > 0) {
-        lines.push('');
-        lines.push(c('bold', '  Recoverable Junk'));
-        const junkData = Object.entries(result.junk.categories).map(([cat, info]) => ({
-            category: cat.charAt(0).toUpperCase() + cat.slice(1),
-            size: formatBytes(info.size)
-        }));
-        lines.push(formatTable(junkData, {
-            columns: [
-                { key: 'category', label: 'Category', width: 40 },
-                { key: 'size', label: 'Savings', width: 18, align: 'right' }
-            ]
-        }));
-        lines.push(`  ${c('dim', `  Total Junk: ${result.junk.count} items / ${result.junk.totalSizeHuman}`)}`);
-    }
-
-    lines.push('');
-    lines.push(c('yellow', '  Run \'filemayor organize\' or \'filemayor clean\' to restore order and reclaim space.'));
-    lines.push('');
-
-    return lines.join('\n');
-}
-
-// ─── Diagnostic (Explain) Report ───────────────────────────────────
-
-/**
- * Format an explain/diagnostic result
- * @param {Object} result - Result from ExplainEngine
- * @returns {string}
- */
-function formatExplainReport(result) {
-    const lines = [];
-    const health = result.health;
-
-    lines.push('');
-    lines.push(c('bold', `  ${health.score > 70 ? SYMBOLS.sparkle : SYMBOLS.warning} ${result.title}`));
-    lines.push(c('dim', `  ${'─'.repeat(40)}`));
-    
-    lines.push(`  ${c('bold', 'Target:')}  ${c('cyan', result.path)}`);
-    
-    // Health Gauge
-    const gauge = progressBar(health.score, 20);
-    lines.push(`  ${c('bold', 'Health:')}  ${c('bold', health.label)} (${gauge})`);
-    
-    lines.push('');
-    lines.push(c('bold', '  Issues Detected:'));
-    if (result.insights.length === 0) {
-        lines.push(`    ${c('green', SYMBOLS.check)} No major issues identified. Clean as a whistle.`);
-    } else {
-        for (const insight of result.insights) {
-            lines.push(`    ${c('yellow', SYMBOLS.bullet)} ${insight}`);
-        }
-    }
-
-    lines.push('');
-    lines.push(c('bold', '  Suggested Treatment:'));
-    lines.push(`    ${c('dim', 'Run')} ${c('yellow', 'filemayor cure')} ${c('dim', 'to generate an AI-powered curative plan.')}`);
-    lines.push('');
-
-    return lines.join('\n');
-}
-
-/**
- * Format a curative plan for terminal display
- */
-function formatCureReport(plan) {
-    const lines = [];
-    lines.push('');
-    lines.push(c('bold', `  ${SYMBOLS.shield} CURATIVE PLAN GENERATED`));
-    lines.push(c('dim', `  ${'─'.repeat(40)}`));
-    
-    lines.push(`  ${c('bold', 'Strategy:')} ${plan.narrative}`);
-    lines.push(`  ${c('bold', 'Confidence:')} ${plan.confidence}%`);
-    
-    lines.push('');
-    lines.push(c('bold', '  Proposed Actions:'));
-    const preview = plan.plan.slice(0, 10).map(p => ({
-        file: p.source.split(/[\\/]/).pop(),
-        to: p.destination.split(/[\\/]/).pop(),
-    }));
-
-    lines.push(formatTable(preview, {
-        columns: [
-            { key: 'file', label: 'File', width: 25 },
-            { key: 'to', label: 'Move to', width: 25 },
-        ]
-    }));
-
-    if (plan.plan.length > 10) {
-        lines.push(`    ${c('dim', `... and ${plan.plan.length - 10} more actions.`)}`);
-    }
-
-    lines.push('');
-    lines.push(c('yellow', `  Run 'filemayor apply' to execute this plan.`));
-    lines.push('');
-
-    return lines.join('\n');
-}
-
-/**
- * Format a duplicate detection report
- */
-function formatDedupeReport(result) {
-    const lines = [];
-    lines.push('');
-    lines.push(c('bold', `  ${SYMBOLS.trash} DUPLICATE ANALYSIS: `) + c('cyan', result.path));
-    lines.push(c('dim', `  ${'─'.repeat(50)}`));
-    
-    if (result.sets === 0) {
-        lines.push(`  ${c('green', SYMBOLS.check)} No duplicates detected. Zero bloat.`);
-        lines.push('');
-        return lines.join('\n');
-    }
-
-    lines.push(`  ${c('red', 'BLOAT DETECTED:')} ${result.sets} duplicate files found.`);
-    lines.push(`  ${c('yellow', 'SAVINGS POTENTIAL:')} ${result.totalWastedHuman}`);
-    lines.push('');
-    
-    lines.push(c('bold', '  Duplicate Items:'));
-    const preview = result.duplicates.slice(0, 10).map(d => ({
-        name: d.duplicate.name.length > 35 ? d.duplicate.name.slice(0, 32) + '...' : d.duplicate.name,
-        size: d.duplicate.sizeHuman,
-    }));
-
-    lines.push(formatTable(preview, {
-        columns: [
-            { key: 'name', label: 'File', width: 37 },
-            { key: 'size', label: 'Wasted', width: 10, align: 'right' }
-        ]
-    }));
-
-    if (result.duplicates.length > 10) {
-        lines.push(`    ${c('dim', `... and ${result.duplicates.length - 10} more duplicates.`)}`);
-    }
-
-    lines.push('');
-    lines.push(c('yellow', `  Run 'filemayor dedupe' to remove these and reclaim space.`));
-    lines.push('');
-
-    return lines.join('\n');
-}
-
-module.exports = {
-    COLORS,
-    SYMBOLS,
-    c,
-    setColors,
-    formatTable,
-    progressBar,
-    Spinner,
-    formatScanReport,
-    formatOrganizeReport,
-    formatCleanReport,
-    formatAnalyzeReport,
-    formatExplainReport,
-    formatCureReport,
-    formatDedupeReport,
-    banner,
-    success,
-    error,
-    warn,
-    info,
-};
+#!/usr/bin/env node
+
+/**
+ * ═══════════════════════════════════════════════════════════════════
+ * FILEMAYOR CORE — REPORTER
+ * Multi-format output (table, JSON, CSV, minimal) with colors,
+ * summary statistics, and machine-readable formats for piping.
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+'use strict';
+
+const { formatBytes } = require('./scanner');
+
+// ─── ANSI Color Codes ─────────────────────────────────────────────
+
+const COLORS = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    italic: '\x1b[3m',
+    underline: '\x1b[4m',
+
+    // Foreground
+    black: '\x1b[30m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    magenta: '\x1b[35m',
+    cyan: '\x1b[36m',
+    white: '\x1b[37m',
+    gray: '\x1b[90m',
+
+    // Bright
+    brightRed: '\x1b[91m',
+    brightGreen: '\x1b[92m',
+    brightYellow: '\x1b[93m',
+    brightBlue: '\x1b[94m',
+    brightMagenta: '\x1b[95m',
+    brightCyan: '\x1b[96m',
+    brightWhite: '\x1b[97m',
+
+    // Background
+    bgRed: '\x1b[41m',
+    bgGreen: '\x1b[42m',
+    bgYellow: '\x1b[43m',
+    bgBlue: '\x1b[44m',
+    bgMagenta: '\x1b[45m',
+    bgCyan: '\x1b[46m',
+};
+
+let _colorsEnabled = true;
+
+function c(color, text) {
+    if (!_colorsEnabled) return text;
+    return `${COLORS[color]}${text}${COLORS.reset}`;
+}
+
+function setColors(enabled) {
+    _colorsEnabled = enabled;
+}
+
+// ─── Symbols ──────────────────────────────────────────────────────
+
+const SYMBOLS = {
+    check: '✓',
+    cross: '✗',
+    arrow: '→',
+    bullet: '•',
+    bar: '█',
+    halfBar: '▓',
+    lightBar: '░',
+    folder: '📂',
+    file: '📄',
+    trash: '🗑️',
+    sparkle: '✨',
+    warning: '⚠️',
+    error: '❌',
+    info: 'ℹ️',
+    clock: '⏱️',
+    shield: '🛡️',
+    eye: '👁️',
+};
+
+// ─── Table Formatter ──────────────────────────────────────────────
+
+/**
+ * Format data as a table with aligned columns
+ * @param {Object[]} data - Array of objects
+ * @param {Object} options - Column config
+ * @returns {string} Formatted table
+ */
+function formatTable(data, options = {}) {
+    if (!data || data.length === 0) return c('dim', '  (no data)');
+
+    const {
+        columns = null,     // Column definitions [{key, label, width, align, format}]
+        maxWidth = null,    // Max column width
+        indent = 2,         // Left indent
+    } = options;
+
+    // Auto-detect columns from data
+    const cols = columns || Object.keys(data[0]).map(key => ({
+        key,
+        label: key.charAt(0).toUpperCase() + key.slice(1),
+        align: 'left'
+    }));
+
+    // Calculate column widths
+    for (const col of cols) {
+        if (!col.width) {
+            const maxDataLen = Math.max(
+                col.label.length,
+                ...data.map(row => {
+                    const val = col.format ? col.format(row[col.key], row) : String(row[col.key] ?? '');
+                    return val.length;
+                })
+            );
+            col.width = maxWidth ? Math.min(maxDataLen, maxWidth) : maxDataLen;
+        }
+    }
+
+    const lines = [];
+    const pad = ' '.repeat(indent);
+
+    // Header
+    const headerLine = cols.map(col => {
+        const label = col.label.padEnd(col.width).slice(0, col.width);
+        return c('bold', label);
+    }).join(c('dim', '  '));
+    lines.push(`${pad}${headerLine}`);
+
+    // Separator
+    const sep = cols.map(col => c('dim', '─'.repeat(col.width))).join(c('dim', '──'));
+    lines.push(`${pad}${sep}`);
+
+    // Rows
+    for (const row of data) {
+        const rowLine = cols.map(col => {
+            let val = col.format ? col.format(row[col.key], row) : String(row[col.key] ?? '');
+            const rawVal = val.replace(/\x1b\[[0-9;]*m/g, ''); // Strip ANSI for length calc
+
+            if (col.align === 'right') {
+                val = ' '.repeat(Math.max(0, col.width - rawVal.length)) + val;
+            } else {
+                val = val + ' '.repeat(Math.max(0, col.width - rawVal.length));
+            }
+            return val;
+        }).join('  ');
+        lines.push(`${pad}${rowLine}`);
+    }
+
+    return lines.join('\n');
+}
+
+// ─── Progress Bar ─────────────────────────────────────────────────
+
+/**
+ * Render a progress bar string
+ * @param {number} percent - 0-100
+ * @param {number} width - Bar width in chars
+ * @returns {string}
+ */
+function progressBar(percent, width = 30) {
+    const clamped = Math.max(0, Math.min(100, percent || 0));
+    const filled = Math.round((clamped / 100) * width);
+    const empty = width - filled;
+    const bar = c('green', SYMBOLS.bar.repeat(filled)) +
+        c('dim', SYMBOLS.lightBar.repeat(empty));
+    return `${bar} ${c('bold', `${clamped}%`)}`;
+}
+
+// ─── Spinner ──────────────────────────────────────────────────────
+
+class Spinner {
+    constructor(message = 'Working...') {
+        this.message = message;
+        this.frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+        this.frameIndex = 0;
+        this.interval = null;
+        this.stream = process.stderr;
+    }
+
+    start() {
+        this.interval = setInterval(() => {
+            const frame = c('cyan', this.frames[this.frameIndex]);
+            this.stream.write(`\r${frame} ${this.message}`);
+            this.frameIndex = (this.frameIndex + 1) % this.frames.length;
+        }, 80);
+        return this;
+    }
+
+    update(message) {
+        this.message = message;
+    }
+
+    succeed(message) {
+        this.stop();
+        this.stream.write(`\r${c('green', SYMBOLS.check)} ${message || this.message}\n`);
+    }
+
+    fail(message) {
+        this.stop();
+        this.stream.write(`\r${c('red', SYMBOLS.cross)} ${message || this.message}\n`);
+    }
+
+    stop() {
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = null;
+            this.stream.write('\r' + ' '.repeat(this.message.length + 10) + '\r');
+        }
+    }
+}
+
+// ─── Scan Report ──────────────────────────────────────────────────
+
+/**
+ * Format a scan result for display
+ * @param {Object} scanResult - Result from scan()
+ * @param {string} format - Output format
+ * @returns {string}
+ */
+function formatScanReport(scanResult, format = 'table') {
+    switch (format) {
+        case 'json':
+            return JSON.stringify(scanResult, null, 2);
+
+        case 'csv':
+            return formatScanCSV(scanResult);
+
+        case 'minimal':
+            return scanResult.files.map(f => f.path).join('\n');
+
+        case 'table':
+        default:
+            return formatScanTable(scanResult);
+    }
+}
+
+function formatScanTable(result) {
+    const lines = [];
+
+    // Header
+    lines.push('');
+    lines.push(c('bold', `  ${SYMBOLS.folder} Scan Report: `) + c('cyan', result.root));
+    lines.push(c('dim', `  ${SYMBOLS.shield} Integrity Check: `) + c('green', 'PASSED'));
+    lines.push(c('dim', `  ${'─'.repeat(60)}`));
+
+    // Category summary
+    const catData = Object.entries(result.stats.categories)
+        .sort((a, b) => b[1] - a[1])
+        .map(([cat, count]) => ({
+            category: cat.charAt(0).toUpperCase() + cat.slice(1),
+            count: String(count),
+        }));
+
+    if (catData.length > 0) {
+        lines.push('');
+        lines.push(c('bold', '  Categories'));
+        lines.push(formatTable(catData, {
+            columns: [
+                { key: 'category', label: 'Category', width: 20 },
+                { key: 'count', label: 'Files', width: 8, align: 'right' },
+            ]
+        }));
+    }
+
+    // File list (top 25)
+    const fileData = result.files.slice(0, 25).map(f => ({
+        name: f.name.length > 40 ? f.name.slice(0, 37) + '...' : f.name,
+        category: f.category,
+        size: f.sizeHuman,
+    }));
+
+    if (fileData.length > 0) {
+        lines.push('');
+        lines.push(c('bold', '  Files'));
+        lines.push(formatTable(fileData, {
+            columns: [
+                { key: 'name', label: 'Name', width: 42 },
+                { key: 'category', label: 'Category', width: 14 },
+                { key: 'size', label: 'Size', width: 10, align: 'right' },
+            ]
+        }));
+
+        if (result.files.length > 25) {
+            lines.push(c('dim', `  ... and ${result.files.length - 25} more files`));
+        }
+    }
+
+    // Summary
+    lines.push('');
+    lines.push(c('dim', `  ${'─'.repeat(60)}`));
+    lines.push(`  ${c('bold', 'Total:')} ${result.stats.filesFound} files, ${formatBytes(result.stats.totalSize)}`);
+    lines.push(`  ${c('bold', 'Scanned:')} ${result.stats.dirsScanned} directories in ${result.stats.durationHuman}`);
+    if (result.stats.errors.length > 0) {
+        lines.push(`  ${c('yellow', SYMBOLS.warning)} ${result.stats.errors.length} errors`);
+    }
+    lines.push('');
+
+    return lines.join('\n');
+}
+
+function formatScanCSV(result) {
+    const header = 'name,path,category,size,modified,ext';
+    const rows = result.files.map(f =>
+        `"${f.name}","${f.path}","${f.category}",${f.size},"${f.modified.toISOString()}","${f.ext}"`
+    );
+    return [header, ...rows].join('\n');
+}
+
+// ─── Organize Report ──────────────────────────────────────────────
+
+function formatOrganizeReport(result, format = 'table') {
+    // Defensive: handle empty/incomplete results
+    if (!result || (!result.plan && !result.planSummary)) {
+        return `\n  ${c('green', SYMBOLS.check)} Nothing to organize — folder is already clean.\n`;
+    }
+    if (!result.plan) result.plan = [];
+    if (!result.planSummary) result.planSummary = { categories: {}, totalFiles: 0, totalSizeHuman: '0 B' };
+
+    switch (format) {
+        case 'json':
+            return JSON.stringify(result, null, 2);
+        case 'csv':
+            return formatOrganizeCSV(result);
+        case 'minimal':
+            return result.plan.map(p => `${p.source} ${SYMBOLS.arrow} ${p.destination}`).join('\n');
+        case 'table':
+        default:
+            return formatOrganizeTable(result);
+    }
+}
+
+function formatOrganizeTable(result) {
+    const lines = [];
+    const plan = result.plan;
+    const isDryRun = result.dryRun;
+
+    lines.push('');
+    if (isDryRun) {
+        lines.push(c('yellow', `  ${SYMBOLS.eye} DRY RUN — No files will be moved`));
+    } else {
+        lines.push(c('green', `  ${SYMBOLS.sparkle} Organization Complete`));
+    }
+    lines.push(c('dim', `  ${SYMBOLS.shield} Integrity Check: `) + c('green', 'PASSED'));
+    lines.push(c('dim', `  ${'─'.repeat(60)}`));
+
+    // Category breakdown
+    const catSummary = result.planSummary.categories;
+    const catData = Object.entries(catSummary)
+        .sort((a, b) => b[1].count - a[1].count)
+        .map(([cat, info]) => ({
+            category: cat,
+            files: String(info.count),
+            size: formatBytes(info.size)
+        }));
+
+    if (catData.length > 0) {
+        lines.push('');
+        lines.push(c('bold', '  Breakdown'));
+        lines.push(formatTable(catData, {
+            columns: [
+                { key: 'category', label: 'Category', width: 20 },
+                { key: 'files', label: 'Files', width: 8, align: 'right' },
+                { key: 'size', label: 'Size', width: 10, align: 'right' },
+            ]
+        }));
+    }
+
+    // Move preview (top 15)
+    const preview = plan.slice(0, 15).map(p => ({
+        from: p.originalName.length > 30 ? p.originalName.slice(0, 27) + '...' : p.originalName,
+        to: p.categoryLabel,
+        action: p.action === 'move' ? c('green', 'move') :
+            p.action === 'skip' ? c('yellow', 'skip') :
+                p.action === 'rename' ? c('cyan', 'rename') :
+                    c('red', p.action)
+    }));
+
+    if (preview.length > 0) {
+        lines.push('');
+        lines.push(c('bold', '  Operations'));
+        lines.push(formatTable(preview, {
+            columns: [
+                { key: 'from', label: 'File', width: 32 },
+                { key: 'to', label: 'Destination', width: 16 },
+                { key: 'action', label: 'Action', width: 10 },
+            ]
+        }));
+
+        if (plan.length > 15) {
+            lines.push(c('dim', `  ... and ${plan.length - 15} more operations`));
+        }
+    }
+
+    // Summary
+    lines.push('');
+    lines.push(c('dim', `  ${'─'.repeat(60)}`));
+    lines.push(`  ${c('bold', 'Total:')} ${result.planSummary.totalFiles} files, ${result.planSummary.totalSizeHuman}`);
+
+    if (!isDryRun && result.execSummary) {
+        const exec = result.execSummary;
+        lines.push(`  ${c('green', SYMBOLS.check)} ${exec.succeeded} succeeded`);
+        if (exec.failed > 0) lines.push(`  ${c('red', SYMBOLS.cross)} ${exec.failed} failed`);
+        if (exec.skipped > 0) lines.push(`  ${c('yellow', '⊘')} ${exec.skipped} skipped`);
+    } else if (isDryRun) {
+        lines.push(c('dim', `  Run without --dry-run to execute these changes`));
+    }
+
+    lines.push('');
+    return lines.join('\n');
+}
+
+function formatOrganizeCSV(result) {
+    const header = 'source,destination,category,original_name,new_name,size,action';
+    const rows = result.plan.map(p =>
+        `"${p.source}","${p.destination}","${p.category}","${p.originalName}","${p.newName}",${p.size},"${p.action}"`
+    );
+    return [header, ...rows].join('\n');
+}
+
+// ─── Clean Report ─────────────────────────────────────────────────
+
+function formatCleanReport(result, format = 'table') {
+    switch (format) {
+        case 'json':
+            return JSON.stringify(result, null, 2);
+        case 'csv':
+            return formatCleanCSV(result);
+        case 'minimal':
+            return result.junk.map(j => `${j.sizeHuman}\t${j.path}`).join('\n');
+        case 'table':
+        default:
+            return formatCleanTable(result);
+    }
+}
+
+function formatCleanTable(result) {
+    const lines = [];
+    const isDryRun = result.dryRun;
+
+    lines.push('');
+    if (isDryRun) {
+        lines.push(c('yellow', `  ${SYMBOLS.eye} DRY RUN — No files will be deleted`));
+    } else if (result.deleteResult) {
+        lines.push(c('green', `  ${SYMBOLS.trash} Cleanup Complete`));
+    } else {
+        lines.push(c('cyan', `  ${SYMBOLS.trash} Junk Scan Results`));
+    }
+    lines.push(c('dim', `  ${SYMBOLS.shield} Integrity Check: `) + c('green', 'PASSED'));
+    lines.push(c('dim', `  ${'─'.repeat(60)}`));
+
+    // Category breakdown
+    const byCategory = result.stats.byCategory;
+    const catData = Object.entries(byCategory)
+        .sort((a, b) => b[1].size - a[1].size)
+        .map(([cat, info]) => ({
+            category: cat.charAt(0).toUpperCase() + cat.slice(1),
+            items: String(info.count),
+            size: formatBytes(info.size)
+        }));
+
+    if (catData.length > 0) {
+        lines.push('');
+        lines.push(c('bold', '  Junk Categories'));
+        lines.push(formatTable(catData, {
+            columns: [
+                { key: 'category', label: 'Category', width: 20 },
+                { key: 'items', label: 'Items', width: 8, align: 'right' },
+                { key: 'size', label: 'Size', width: 10, align: 'right' },
+            ]
+        }));
+    }
+
+    // Largest items (top 10)
+    const sorted = [...result.junk].sort((a, b) => b.size - a.size).slice(0, 10);
+    const itemData = sorted.map(j => ({
+        name: j.name.length > 35 ? j.name.slice(0, 32) + '...' : j.name,
+        type: j.type === 'directory' ? c('blue', 'DIR') : c('dim', 'FILE'),
+        size: j.sizeHuman,
+    }));
+
+    if (itemData.length > 0) {
+        lines.push('');
+        lines.push(c('bold', '  Largest Junk Items'));
+        lines.push(formatTable(itemData, {
+            columns: [
+                { key: 'name', label: 'Name', width: 37 },
+                { key: 'type', label: 'Type', width: 6 },
+                { key: 'size', label: 'Size', width: 10, align: 'right' },
+            ]
+        }));
+    }
+
+    // Summary
+    lines.push('');
+    lines.push(c('dim', `  ${'─'.repeat(60)}`));
+    lines.push(`  ${c('bold', 'Total junk:')} ${result.stats.filesFound + result.stats.dirsFound} items, ${result.stats.totalSizeHuman}`);
+
+    if (result.deleteResult) {
+        const dr = result.deleteResult;
+        lines.push(`  ${c('green', SYMBOLS.check)} Deleted ${dr.deleted} items, freed ${dr.freedHuman}`);
+        if (dr.errors.length > 0) {
+            lines.push(`  ${c('red', SYMBOLS.cross)} ${dr.errors.length} errors`);
+        }
+    } else if (isDryRun) {
+        lines.push(c('dim', `  Run without --dry-run to clean these files`));
+    }
+
+    lines.push('');
+    return lines.join('\n');
+}
+
+function formatCleanCSV(result) {
+    const header = 'name,path,category,type,size';
+    const rows = result.junk.map(j =>
+        `"${j.name}","${j.path}","${j.category}","${j.type}",${j.size}`
+    );
+    return [header, ...rows].join('\n');
+}
+
+// ─── Generic Utilities ────────────────────────────────────────────
+
+/**
+ * Print a header banner
+ */
+function banner() {
+    return [
+        '',
+        c('bold', `  ${SYMBOLS.sparkle} FileMayor`) + c('dim', ' — Your Digital Life Organizer'),
+        c('dim', '  by Lehlohonolo Goodwill Nchefu (Chevza)'),
+        c('dim', `  ${'─'.repeat(50)}`),
+        ''
+    ].join('\n');
+}
+
+/**
+ * Print a success message
+ */
+function success(msg) {
+    return `${c('green', SYMBOLS.check)} ${msg}`;
+}
+
+/**
+ * Print an error message
+ */
+function error(msg) {
+    return `${c('red', SYMBOLS.cross)} ${msg}`;
+}
+
+/**
+ * Print a warning message
+ */
+function warn(msg) {
+    return `${c('yellow', SYMBOLS.warning)} ${msg}`;
+}
+
+/**
+ * Print an info message
+ */
+function info(msg) {
+    return `${c('cyan', SYMBOLS.info)} ${msg}`;
+}
+
+// ─── Analyze Report ────────────────────────────────────────────────
+
+function formatAnalyzeReport(result, format = 'table') {
+    if (format === 'json') return JSON.stringify(result, null, 2);
+
+    const lines = [];
+    lines.push('');
+    lines.push(c('bold', `  ${SYMBOLS.eye} Deep Intelligence Report: `) + c('cyan', result.root));
+    lines.push(c('dim', `  ${'─'.repeat(60)}`));
+
+    // Summary Insights
+    lines.push('');
+    lines.push(`  ${c('bold', 'Summary:')}   ${result.summary.totalFiles} files detected. Total size: ${result.summary.totalSizeHuman}`);
+    lines.push(`  ${c('green', '⚡ Insight:')}  You can reclaim ${c('bold', result.summary.potentialSavingsHuman)} today.`);
+
+    // Duplicates Section
+    if (result.duplicates.sets > 0) {
+        lines.push('');
+        lines.push(c('bold', '  Duplicate Bloat'));
+        const dupeData = result.duplicates.details.map(d => ({
+            name: d.files[0].name.length > 35 ? d.files[0].name.slice(0, 32) + '...' : d.files[0].name,
+            count: String(d.files.length),
+            wasted: d.wastedSpaceHuman
+        }));
+        lines.push(formatTable(dupeData, {
+            columns: [
+                { key: 'name', label: 'File Name', width: 37 },
+                { key: 'count', label: 'Copies', width: 8, align: 'right' },
+                { key: 'wasted', label: 'Wasted', width: 10, align: 'right' }
+            ]
+        }));
+        lines.push(`  ${c('dim', `  Found ${result.duplicates.sets} duplicate sets causing ${result.duplicates.totalWastedHuman} bloat.`)}`);
+    }
+
+    // Largest Folders Section
+    if (result.largestDirs.length > 0) {
+        lines.push('');
+        lines.push(c('bold', '  Top Space Consumers (Bloat Map)'));
+        const dirData = result.largestDirs.map(d => ({
+            name: d.name.length > 37 ? d.name.slice(0, 34) + '...' : d.name,
+            files: String(d.count),
+            size: d.sizeHuman
+        }));
+        lines.push(formatTable(dirData, {
+            columns: [
+                { key: 'name', label: 'Directory', width: 40 },
+                { key: 'files', label: 'Files', width: 8, align: 'right' },
+                { key: 'size', label: 'Size', width: 10, align: 'right' }
+            ]
+        }));
+    }
+
+    // Junk Section
+    if (result.junk.count > 0) {
+        lines.push('');
+        lines.push(c('bold', '  Recoverable Junk'));
+        const junkData = Object.entries(result.junk.categories).map(([cat, info]) => ({
+            category: cat.charAt(0).toUpperCase() + cat.slice(1),
+            size: formatBytes(info.size)
+        }));
+        lines.push(formatTable(junkData, {
+            columns: [
+                { key: 'category', label: 'Category', width: 40 },
+                { key: 'size', label: 'Savings', width: 18, align: 'right' }
+            ]
+        }));
+        lines.push(`  ${c('dim', `  Total Junk: ${result.junk.count} items / ${result.junk.totalSizeHuman}`)}`);
+    }
+
+    lines.push('');
+    lines.push(c('yellow', '  Run \'filemayor organize\' or \'filemayor clean\' to restore order and reclaim space.'));
+    lines.push('');
+
+    return lines.join('\n');
+}
+
+// ─── Diagnostic (Explain) Report ───────────────────────────────────
+
+/**
+ * Format an explain/diagnostic result
+ * @param {Object} result - Result from ExplainEngine
+ * @returns {string}
+ */
+function formatExplainReport(result) {
+    const lines = [];
+    const health = result.health;
+
+    lines.push('');
+    lines.push(c('bold', `  ${health.score > 70 ? SYMBOLS.sparkle : SYMBOLS.warning} ${result.title}`));
+    lines.push(c('dim', `  ${'─'.repeat(40)}`));
+    
+    lines.push(`  ${c('bold', 'Target:')}  ${c('cyan', result.path)}`);
+    
+    // Health Gauge
+    const gauge = progressBar(health.score, 20);
+    lines.push(`  ${c('bold', 'Health:')}  ${c('bold', health.label)} (${gauge})`);
+    
+    lines.push('');
+    lines.push(c('bold', '  Issues Detected:'));
+    if (result.insights.length === 0) {
+        lines.push(`    ${c('green', SYMBOLS.check)} No major issues identified. Clean as a whistle.`);
+    } else {
+        for (const insight of result.insights) {
+            lines.push(`    ${c('yellow', SYMBOLS.bullet)} ${insight}`);
+        }
+    }
+
+    lines.push('');
+    lines.push(c('bold', '  Suggested Treatment:'));
+    lines.push(`    ${c('dim', 'Run')} ${c('yellow', 'filemayor cure')} ${c('dim', 'to generate an AI-powered curative plan.')}`);
+    lines.push('');
+
+    return lines.join('\n');
+}
+
+/**
+ * Format a curative plan for terminal display
+ */
+function formatCureReport(plan) {
+    const lines = [];
+    lines.push('');
+    lines.push(c('bold', `  ${SYMBOLS.shield} CURATIVE PLAN GENERATED`));
+    lines.push(c('dim', `  ${'─'.repeat(40)}`));
+    
+    lines.push(`  ${c('bold', 'Strategy:')} ${plan.narrative}`);
+    lines.push(`  ${c('bold', 'Confidence:')} ${plan.confidence}%`);
+    
+    lines.push('');
+    lines.push(c('bold', '  Proposed Actions:'));
+    const preview = plan.plan.slice(0, 10).map(p => ({
+        file: p.source.split(/[\\/]/).pop(),
+        to: p.destination.split(/[\\/]/).pop(),
+    }));
+
+    lines.push(formatTable(preview, {
+        columns: [
+            { key: 'file', label: 'File', width: 25 },
+            { key: 'to', label: 'Move to', width: 25 },
+        ]
+    }));
+
+    if (plan.plan.length > 10) {
+        lines.push(`    ${c('dim', `... and ${plan.plan.length - 10} more actions.`)}`);
+    }
+
+    lines.push('');
+    lines.push(c('yellow', `  Run 'filemayor apply' to execute this plan.`));
+    lines.push('');
+
+    return lines.join('\n');
+}
+
+/**
+ * Format a duplicate detection report
+ */
+function formatDedupeReport(result) {
+    const lines = [];
+    lines.push('');
+    lines.push(c('bold', `  ${SYMBOLS.trash} DUPLICATE ANALYSIS: `) + c('cyan', result.path));
+    lines.push(c('dim', `  ${'─'.repeat(50)}`));
+    
+    if (result.sets === 0) {
+        lines.push(`  ${c('green', SYMBOLS.check)} No duplicates detected. Zero bloat.`);
+        lines.push('');
+        return lines.join('\n');
+    }
+
+    lines.push(`  ${c('red', 'BLOAT DETECTED:')} ${result.sets} duplicate files found.`);
+    lines.push(`  ${c('yellow', 'SAVINGS POTENTIAL:')} ${result.totalWastedHuman}`);
+    lines.push('');
+    
+    lines.push(c('bold', '  Duplicate Items:'));
+    const preview = result.duplicates.slice(0, 10).map(d => ({
+        name: d.duplicate.name.length > 35 ? d.duplicate.name.slice(0, 32) + '...' : d.duplicate.name,
+        size: d.duplicate.sizeHuman,
+    }));
+
+    lines.push(formatTable(preview, {
+        columns: [
+            { key: 'name', label: 'File', width: 37 },
+            { key: 'size', label: 'Wasted', width: 10, align: 'right' }
+        ]
+    }));
+
+    if (result.duplicates.length > 10) {
+        lines.push(`    ${c('dim', `... and ${result.duplicates.length - 10} more duplicates.`)}`);
+    }
+
+    lines.push('');
+    lines.push(c('yellow', `  Run 'filemayor dedupe' to remove these and reclaim space.`));
+    lines.push('');
+
+    return lines.join('\n');
+}
+
+module.exports = {
+    COLORS,
+    SYMBOLS,
+    c,
+    setColors,
+    formatTable,
+    progressBar,
+    Spinner,
+    formatScanReport,
+    formatOrganizeReport,
+    formatCleanReport,
+    formatAnalyzeReport,
+    formatExplainReport,
+    formatCureReport,
+    formatDedupeReport,
+    banner,
+    success,
+    error,
+    warn,
+    info,
+};