filemayor 2.1.0 → 3.6.0

package/core/organizer.js

@@ -14,7 +14,10 @@ const fs = require('fs');
 const path = require('path');
 const { categorize, getCategories } = require('./categories');
 const { scan } = require('./scanner');
-const { validatePath, isFileSafe, sanitizeFilename, canWrite, createSnapshot } = require('./security');
+const { 
+    validatePath, isFileSafe, sanitizeFilename, canWrite, createSnapshot,
+    findNearestSubstrate 
+} = require('./security');
 const { formatBytes } = require('./scanner');
 
 // ─── Naming Conventions ───────────────────────────────────────────
@@ -175,6 +178,13 @@ function generatePlan(srcDir, options = {}) {
 
     // Build the plan
     for (const file of scanResult.files) {
+        // Substrate Protection (v3.5)
+        // If file is inside a project substrate, DO NOT scatter it by default
+        const projectRoot = findNearestSubstrate(file.path);
+        if (projectRoot) {
+            continue; // Skip project-locked files
+        }
+
         const category = file.category;
         categoryCounts[category] = (categoryCounts[category] || 0);
 
@@ -241,22 +251,23 @@ function generatePlan(srcDir, options = {}) {
 
 // ─── Execution ────────────────────────────────────────────────────
 
+const FileMayorFS = require('./fs-abstraction');
+const fmfs = new FileMayorFS();
+
 /**
  * Execute a move plan with journal logging for rollback
  * @param {MovePlanItem[]} plan - The move plan to execute
  * @param {Object} options - Execution options
  * @returns {{ results: Object[], journal: Object[], summary: Object }}
  */
-function executePlan(plan, options = {}) {
+async function executePlan(plan, options = {}) {
     const {
         onProgress = null,
         onError = null,
-        journalPath = null,   // Path to save rollback journal
-        abortOnError = false, // Stop on first error
+        abortOnError = false,
     } = options;
 
     const results = [];
-    const journal = [];
     let succeeded = 0;
     let failed = 0;
     let skipped = 0;
@@ -264,7 +275,6 @@ function executePlan(plan, options = {}) {
     for (let i = 0; i < plan.length; i++) {
         const item = plan[i];
 
-        // Progress callback
         if (onProgress) {
             onProgress({
                 current: i + 1,
@@ -276,104 +286,21 @@ function executePlan(plan, options = {}) {
             });
         }
 
-        // Skip items marked as skip
         if (item.action === 'skip') {
             results.push({ ...item, status: 'skipped', error: null });
             skipped++;
             continue;
         }
 
-        // Safety check
-        const safeCheck = isFileSafe(item.source);
-        if (!safeCheck.safe) {
-            const error = `Safety check failed: ${safeCheck.reason}`;
-            results.push({ ...item, status: 'error', error });
-            failed++;
-            if (onError) onError({ item, error });
-            if (abortOnError) break;
-            continue;
-        }
-
-        // Create destination directory
-        const destDir = path.dirname(item.destination);
         try {
-            fs.mkdirSync(destDir, { recursive: true });
-        } catch (err) {
-            const error = `Failed to create directory: ${err.message}`;
-            results.push({ ...item, status: 'error', error });
-            failed++;
-            if (onError) onError({ item, error });
-            if (abortOnError) break;
-            continue;
-        }
-
-        // Create pre-move snapshot for integrity
-        const snapshot = createSnapshot(item.source);
-
-        // Execute the move
-        try {
-            // Handle overwrite
-            if (item.action === 'overwrite' && fs.existsSync(item.destination)) {
-                fs.unlinkSync(item.destination);
-            }
-
-            // Perform the move
-            fs.renameSync(item.source, item.destination);
-
-            // Journal entry for rollback
-            const journalEntry = {
-                source: item.source,
-                destination: item.destination,
-                originalName: item.originalName,
-                newName: item.newName,
-                size: item.size,
-                timestamp: Date.now(),
-                snapshot
-            };
-            journal.push(journalEntry);
-
+            await fmfs.move(item.source, item.destination);
             results.push({ ...item, status: 'success', error: null });
             succeeded++;
         } catch (err) {
-            // If rename fails (cross-device), try copy + delete
-            try {
-                fs.copyFileSync(item.source, item.destination);
-                fs.unlinkSync(item.source);
-
-                const journalEntry = {
-                    source: item.source,
-                    destination: item.destination,
-                    originalName: item.originalName,
-                    newName: item.newName,
-                    size: item.size,
-                    timestamp: Date.now(),
-                    snapshot,
-                    crossDevice: true
-                };
-                journal.push(journalEntry);
-
-                results.push({ ...item, status: 'success', error: null });
-                succeeded++;
-            } catch (copyErr) {
-                const error = `Move failed: ${copyErr.message}`;
-                results.push({ ...item, status: 'error', error });
-                failed++;
-                if (onError) onError({ item, error });
-                if (abortOnError) break;
-            }
-        }
-    }
-
-    // Save journal to disk if path provided
-    if (journalPath && journal.length > 0) {
-        try {
-            const existing = fs.existsSync(journalPath)
-                ? JSON.parse(fs.readFileSync(journalPath, 'utf8'))
-                : [];
-            const merged = [...existing, ...journal];
-            fs.writeFileSync(journalPath, JSON.stringify(merged, null, 2), 'utf8');
-        } catch (err) {
-            // Journal save failed — non-fatal
+            results.push({ ...item, status: 'error', error: err.message });
+            failed++;
+            if (onError) onError({ item, error: err.message });
+            if (abortOnError) break;
         }
     }
 
@@ -386,7 +313,7 @@ function executePlan(plan, options = {}) {
         totalSizeHuman: formatBytes(plan.reduce((sum, p) => sum + p.size, 0))
     };
 
-    return { results, journal, summary };
+    return { results, journal: fmfs.getJournal(), summary };
 }
 
 // ─── Rollback (Undo) ──────────────────────────────────────────────
@@ -395,50 +322,11 @@ function executePlan(plan, options = {}) {
  * Rollback operations using a journal
  * @param {Object[]} journal - Journal entries from executePlan
  * @param {Object} options - Rollback options
- * @returns {{ undone: number, failed: number, errors: string[] }}
  */
-function rollback(journal, options = {}) {
-    const { onProgress = null } = options;
-    let undone = 0;
-    let failed = 0;
-    const errors = [];
-
-    // Process in reverse order (most recent first)
-    const reversed = [...journal].reverse();
-
-    for (let i = 0; i < reversed.length; i++) {
-        const entry = reversed[i];
-
-        if (onProgress) {
-            onProgress({
-                current: i + 1,
-                total: reversed.length,
-                percent: Math.round(((i + 1) / reversed.length) * 100),
-                file: entry.originalName
-            });
-        }
-
-        try {
-            // Ensure source directory exists
-            const sourceDir = path.dirname(entry.source);
-            fs.mkdirSync(sourceDir, { recursive: true });
-
-            // Move back
-            if (entry.crossDevice) {
-                fs.copyFileSync(entry.destination, entry.source);
-                fs.unlinkSync(entry.destination);
-            } else {
-                fs.renameSync(entry.destination, entry.source);
-            }
-
-            undone++;
-        } catch (err) {
-            failed++;
-            errors.push(`Failed to undo ${entry.originalName}: ${err.message}`);
-        }
-    }
-
-    return { undone, failed, errors };
+async function rollback(journal, options = {}) {
+    // Fill the fmfs internal journal with the passed journal to use its logic
+    fmfs.sessionJournal = journal;
+    return await fmfs.rollback();
 }
 
 /**
@@ -463,13 +351,12 @@ function loadJournal(journalPath) {
  * @param {Object} options - Full options
  * @returns {{ results: Object[], journal: Object[], planSummary: Object, execSummary: Object }}
  */
-function organize(dirPath, options = {}) {
+async function organize(dirPath, options = {}) {
     const {
         dryRun = false,
         naming = 'original',
         outputDir = null,
         duplicateStrategy = 'rename',
-        journalPath = null,
         onProgress = null,
         onError = null,
         abortOnError = false,
@@ -498,10 +385,9 @@ function organize(dirPath, options = {}) {
     }
 
     // Execute
-    const { results, journal, summary: execSummary } = executePlan(plan, {
+    const { results, journal, summary: execSummary } = await executePlan(plan, {
         onProgress,
         onError,
-        journalPath: journalPath || path.join(dirPath, '.filemayor-journal.json'),
         abortOnError
     });
 

package/core/reporter.js

@@ -163,11 +163,12 @@ function formatTable(data, options = {}) {
  * @returns {string}
  */
 function progressBar(percent, width = 30) {
-    const filled = Math.round((percent / 100) * width);
+    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', `${percent}%`)}`;
+    return `${bar} ${c('bold', `${clamped}%`)}`;
 }
 
 // ─── Spinner ──────────────────────────────────────────────────────
@@ -313,6 +314,13 @@ function formatScanCSV(result) {
 // ─── 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);
@@ -633,6 +641,125 @@ function formatAnalyzeReport(result, format = 'table') {
     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,
@@ -645,6 +772,9 @@ module.exports = {
     formatOrganizeReport,
     formatCleanReport,
     formatAnalyzeReport,
+    formatExplainReport,
+    formatCureReport,
+    formatDedupeReport,
     banner,
     success,
     error,

package/core/scanner.js

@@ -130,38 +130,33 @@ class Scanner {
      * @returns {{ files: Object[], stats: Object }}
      */
     scan(dirPath) {
-        // Validate the path
-        const validation = validatePath(dirPath);
-        if (!validation.valid) {
-            throw new Error(`Invalid path: ${validation.error}`);
-        }
+        const validation = this._validate(dirPath);
+        this.stats.startTime = Date.now();
+        const files = [];
 
-        const safeCheck = isDirSafe(validation.resolved);
-        if (!safeCheck.safe) {
-            throw new Error(`Unsafe directory: ${safeCheck.reason}`);
-        }
+        this._scanRecursive(validation.resolved, validation.resolved, 0, files);
 
-        if (!canRead(validation.resolved)) {
-            throw new Error(`Permission denied: cannot read "${validation.resolved}"`);
-        }
+        this.stats.endTime = Date.now();
+        this.stats.duration = this.stats.endTime - this.stats.startTime;
+        this.stats.durationHuman = this._formatDuration(this.stats.duration);
 
-        // Verify it's actually a directory
-        try {
-            const stat = fs.statSync(validation.resolved);
-            if (!stat.isDirectory()) {
-                throw new Error(`Not a directory: "${validation.resolved}"`);
-            }
-        } catch (err) {
-            if (err.code === 'ENOENT') {
-                throw new Error(`Directory not found: "${validation.resolved}"`);
-            }
-            throw err;
-        }
+        return {
+            root: validation.resolved,
+            files,
+            stats: { ...this.stats }
+        };
+    }
 
+    /**
+     * Asynchronous scan for higher performance and non-blocking operation
+     * @param {string} dirPath 
+     */
+    async scanAsync(dirPath) {
+        const validation = this._validate(dirPath);
         this.stats.startTime = Date.now();
         const files = [];
 
-        this._scanRecursive(validation.resolved, validation.resolved, 0, files);
+        await this._scanRecursiveAsync(validation.resolved, validation.resolved, 0, files);
 
         this.stats.endTime = Date.now();
         this.stats.duration = this.stats.endTime - this.stats.startTime;
@@ -174,22 +169,35 @@ class Scanner {
         };
     }
 
+    /**
+     * Shared validation logic
+     */
+    _validate(dirPath) {
+        const validation = validatePath(dirPath);
+        if (!validation.valid) throw new Error(`Invalid path: ${validation.error}`);
+
+        const safeCheck = isDirSafe(validation.resolved);
+        if (!safeCheck.safe) throw new Error(`Unsafe directory: ${safeCheck.reason}`);
+
+        if (!canRead(validation.resolved)) {
+            throw new Error(`Permission denied: cannot read "${validation.resolved}"`);
+        }
+
+        return validation;
+    }
+
     /**
      * Internal recursive scan implementation
      */
     _scanRecursive(dir, rootPath, depth, results) {
-        // Check abort signal
         if (this._aborted || this.options.abortSignal?.aborted) {
             this._aborted = true;
             return;
         }
 
-        // Depth limit
         if (depth > this.options.maxDepth) return;
-
         this.stats.dirsScanned++;
 
-        // Progress callback
         if (this.options.onProgress) {
             this.options.onProgress({
                 phase: 'scanning',
@@ -204,39 +212,25 @@ class Scanner {
         try {
             items = fs.readdirSync(dir, { withFileTypes: true });
         } catch (err) {
-            const errorInfo = {
-                path: dir,
-                code: err.code,
-                message: err.message,
-                depth
-            };
-            this.stats.errors.push(errorInfo);
-            if (this.options.onError) {
-                this.options.onError(errorInfo);
-            }
+            this.stats.errors.push({ path: dir, code: err.code, message: err.message });
+            if (this.options.onError) this.options.onError({ path: dir, error: err.message });
             return;
         }
 
         for (const item of items) {
             if (this._aborted) return;
-
             const fullPath = path.join(dir, item.name);
 
-            // ─── Filtering ────────────────────────────────
-
-            // Skip hidden files/dirs
             if (!this.options.includeHidden && item.name.startsWith('.')) {
                 this.stats.skipped++;
                 continue;
             }
 
-            // Skip ignored directories
             if (item.isDirectory() && this.options.ignore.includes(item.name)) {
                 this.stats.skipped++;
                 continue;
             }
 
-            // Skip by glob patterns
             if (this.options.ignorePatterns.length > 0) {
                 const shouldSkip = this.options.ignorePatterns.some(p => matchGlob(p, item.name));
                 if (shouldSkip) {
@@ -245,38 +239,25 @@ class Scanner {
                 }
             }
 
-            // Handle symlinks
             if (item.isSymbolicLink && item.isSymbolicLink() && !this.options.followSymlinks) {
                 this.stats.skipped++;
                 continue;
             }
 
-            // ─── Process Entry ────────────────────────────
-
             let stats;
             try {
-                stats = this.options.followSymlinks
-                    ? fs.statSync(fullPath)
-                    : fs.lstatSync(fullPath);
+                stats = this.options.followSymlinks ? fs.statSync(fullPath) : fs.lstatSync(fullPath);
             } catch (err) {
-                this.stats.errors.push({
-                    path: fullPath,
-                    code: err.code,
-                    message: err.message,
-                    depth
-                });
+                this.stats.errors.push({ path: fullPath, code: err.code, message: err.message });
                 continue;
             }
 
             if (stats.isFile()) {
-                // Apply file filters
                 if (this._shouldIncludeFile(fullPath, stats)) {
                     const fileInfo = buildFileInfo(fullPath, stats, rootPath);
                     results.push(fileInfo);
                     this.stats.filesFound++;
                     this.stats.totalSize += stats.size;
-
-                    // Track category counts
                     const cat = fileInfo.category;
                     this.stats.categories[cat] = (this.stats.categories[cat] || 0) + 1;
                 } else {
@@ -284,14 +265,63 @@ class Scanner {
                 }
             } else if (stats.isDirectory()) {
                 if (this.options.includeDirectories) {
-                    const dirInfo = buildFileInfo(fullPath, stats, rootPath);
-                    results.push(dirInfo);
+                    results.push(buildFileInfo(fullPath, stats, rootPath));
                 }
                 this._scanRecursive(fullPath, rootPath, depth + 1, results);
             }
         }
     }
 
+    /**
+     * Async recursive scan using promises
+     */
+    async _scanRecursiveAsync(dir, rootPath, depth, results) {
+        if (this._aborted || this.options.abortSignal?.aborted) {
+            this._aborted = true;
+            return;
+        }
+
+        if (depth > this.options.maxDepth) return;
+        this.stats.dirsScanned++;
+
+        let items;
+        try {
+            items = await fs.promises.readdir(dir, { withFileTypes: true });
+        } catch (err) {
+            this.stats.errors.push({ path: dir, code: err.code, message: err.message });
+            return;
+        }
+
+        const promises = items.map(async (item) => {
+            if (this._aborted) return;
+            const fullPath = path.join(dir, item.name);
+
+            // Filtering
+            if (!this.options.includeHidden && item.name.startsWith('.')) return;
+            if (item.isDirectory() && this.options.ignore.includes(item.name)) return;
+
+            let stats;
+            try {
+                stats = await fs.promises.lstat(fullPath);
+            } catch (err) { return; }
+
+            if (stats.isFile()) {
+                if (this._shouldIncludeFile(fullPath, stats)) {
+                    const fileInfo = buildFileInfo(fullPath, stats, rootPath);
+                    results.push(fileInfo);
+                    this.stats.filesFound++;
+                    this.stats.totalSize += stats.size;
+                    const cat = fileInfo.category;
+                    this.stats.categories[cat] = (this.stats.categories[cat] || 0) + 1;
+                }
+            } else if (stats.isDirectory()) {
+                await this._scanRecursiveAsync(fullPath, rootPath, depth + 1, results);
+            }
+        });
+
+        await Promise.all(promises);
+    }
+
     /**
      * Check if a file passes all configured filters
      */