filemayor 2.0.5 → 3.6.0

package/core/analyzer.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+
+/**
+ * ═══════════════════════════════════════════════════════════════════
+ * FILEMAYOR CORE — ANALYZER
+ * Deep filesystem insights: duplicate detection, bloat mapping,
+ * and potential savings calculation.
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { scan } = require('./scanner');
+const { findJunk } = require('./cleaner');
+const { formatBytes } = require('./scanner');
+
+/**
+ * Analyze a directory for duplicates, bloat, and junk
+ * @param {string} dirPath - Root directory to analyze
+ * @param {Object} options - Analysis options
+ * @returns {Object} Deep analysis results
+ */
+function analyzeDirectory(dirPath, options = {}) {
+    const {
+        maxDepth = 10,
+        minSize = 1024, // Ignore files smaller than 1KB for duplicate analysis
+    } = options;
+
+    // 1. Initial Scan
+    const scanResult = scan(dirPath, { maxDepth, includeDirectories: true });
+    const { files, stats } = scanResult;
+
+    // 2. Duplicate Detection (Size-first hashing)
+    const sizeMap = new Map();
+    const duplicates = [];
+
+    // Group by size first (fast)
+    for (const file of files) {
+        if (file.size < minSize) continue;
+        if (!sizeMap.has(file.size)) {
+            sizeMap.set(file.size, []);
+        }
+        sizeMap.get(file.size).push(file);
+    }
+
+    // Hash only those with identical sizes
+    for (const [size, candidateFiles] of sizeMap.entries()) {
+        if (candidateFiles.length < 2) continue;
+
+        const hashMap = new Map();
+        for (const file of candidateFiles) {
+            try {
+                // Partial hash (first 16KB) for efficiency
+                const hash = getFileHash(file.path, 16384);
+                if (!hashMap.has(hash)) {
+                    hashMap.set(hash, []);
+                }
+                hashMap.get(hash).push(file);
+            } catch (err) {
+                // Skip files we can't read
+            }
+        }
+
+        for (const [hash, dupeFiles] of hashMap.entries()) {
+            if (dupeFiles.length > 1) {
+                duplicates.push({
+                    size,
+                    sizeHuman: formatBytes(size),
+                    files: dupeFiles.map(f => ({ name: f.name, path: f.path, relativePath: f.relativePath })),
+                    wastedSpace: size * (dupeFiles.length - 1),
+                    wastedSpaceHuman: formatBytes(size * (dupeFiles.length - 1))
+                });
+            }
+        }
+    }
+    // 3. Bloat Mapping (Top Directories) & Progress Reporting
+    const dirMap = new Map();
+    for (let i = 0; i < files.length; i++) {
+        const file = files[i];
+
+        // Progress callback
+        if (options.onProgress) {
+            options.onProgress({
+                current: i + 1,
+                total: files.length,
+                percent: Math.round(((i + 1) / files.length) * 100),
+                file: file.name
+            });
+        }
+
+        const parts = file.relativePath.split(path.sep);
+        let currentPath = '';
+        // Only track top-level and second-level folders for bloat mapping
+        for (let j = 0; j < Math.min(parts.length - 1, 2); j++) {
+            currentPath = currentPath ? path.join(currentPath, parts[j]) : parts[j];
+            if (!dirMap.has(currentPath)) {
+                dirMap.set(currentPath, { size: 0, count: 0 });
+            }
+            const info = dirMap.get(currentPath);
+            info.size += file.size;
+            info.count += 1;
+        }
+    }
+
+    const largestDirs = Array.from(dirMap.entries())
+        .map(([name, info]) => ({ name, ...info, sizeHuman: formatBytes(info.size) }))
+        .sort((a, b) => b.size - a.size)
+        .slice(0, 5);
+
+    // 4. Junk Detection Integration
+    const junkResult = findJunk(dirPath, { maxDepth });
+    const totalJunkSize = junkResult.stats.totalSize;
+    const totalDuplicateWasted = duplicates.reduce((sum, d) => sum + d.wastedSpace, 0);
+
+    return {
+        root: dirPath,
+        timestamp: Date.now(),
+        summary: {
+            totalFiles: stats.filesFound,
+            totalSize: stats.totalSize,
+            totalSizeHuman: formatBytes(stats.totalSize),
+            potentialSavings: totalJunkSize + totalDuplicateWasted,
+            potentialSavingsHuman: formatBytes(totalJunkSize + totalDuplicateWasted)
+        },
+        duplicates: {
+            sets: duplicates.length,
+            totalWasted: totalDuplicateWasted,
+            totalWastedHuman: formatBytes(totalDuplicateWasted),
+            details: duplicates.sort((a, b) => b.wastedSpace - a.wastedSpace).slice(0, 10)
+        },
+        largestDirs,
+        junk: {
+            count: junkResult.junk.length,
+            totalSize: totalJunkSize,
+            totalSizeHuman: formatBytes(totalJunkSize),
+            categories: junkResult.stats.byCategory
+        }
+    };
+}
+
+/**
+ * Get hash of file content (partial or full)
+ */
+function getFileHash(filePath, limit = null) {
+    const buffer = limit
+        ? Buffer.alloc(limit)
+        : fs.readFileSync(filePath);
+
+    if (limit) {
+        const fd = fs.openSync(filePath, 'r');
+        fs.readSync(fd, buffer, 0, limit, 0);
+        fs.closeSync(fd);
+    }
+
+    return crypto.createHash('md5').update(buffer).digest('hex');
+}
+
+module.exports = {
+    analyzeDirectory
+};

package/core/emergency-halt.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+
+/**
+ * ═══════════════════════════════════════════════════════════════════
+ * FILEMAYOR CORE — EMERGENCY HALT HANDLER ("The Black Box")
+ * 
+ * Intercepts Ctrl+C, SIGTERM, and uncaught exceptions to ensure
+ * the Master Journal is flushed to disk before the process dies.
+ * Without this, a partial batch leaves an un-recoverable mess.
+ * 
+ * Uses writeFileSync to BLOCK the event loop during flush —
+ * guaranteeing the JSON data reaches the SSD even during panic.
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+let _isInitialized = false;
+let _journalRef = null;
+let _journalPath = null;
+
+/**
+ * Initialize the Emergency Halt handler.
+ * Call this ONCE at the start of any batch operation.
+ * 
+ * @param {Array} journalRef - Reference to the live journal array
+ * @param {string} journalPath - Absolute path to the journal file
+ */
+function initEmergencyHalt(journalRef, journalPath) {
+    if (_isInitialized) return; // Prevent double-registration
+
+    _journalRef = journalRef;
+    _journalPath = journalPath;
+    _isInitialized = true;
+
+    const flushJournal = (reason) => {
+        if (!_journalRef || _journalRef.length === 0) return;
+
+        console.log(`\n\n🛑 [EMERGENCY HALT] ${reason}`);
+        console.log('   Saving progress to Master Journal...');
+
+        try {
+            const data = JSON.stringify(_journalRef, null, 2);
+
+            // CRITICAL: writeFileSync blocks the event loop to guarantee persistence
+            // Permission 0o600 = owner-only read/write (anti-journal-poisoning)
+            fs.writeFileSync(_journalPath, data, { mode: 0o600 });
+
+            console.log(`   ✅ Progress saved (${_journalRef.length} entries).`);
+            console.log(`   Run 'filemayor undo' to revert.`);
+        } catch (err) {
+            console.error(`   ❌ CRITICAL: Could not save Journal: ${err.message}`);
+        }
+    };
+
+    // Intercept Ctrl+C (SIGINT), Terminal Closure (SIGTERM), HUP
+    const signals = ['SIGINT', 'SIGTERM'];
+    // SIGHUP is not available on Windows, add conditionally
+    if (process.platform !== 'win32') signals.push('SIGHUP');
+
+    for (const signal of signals) {
+        process.on(signal, () => {
+            flushJournal(`Received ${signal}`);
+            process.exit(130); // Standard exit code for signal termination
+        });
+    }
+
+    // Catch unexpected crashes (the "Vibe-Coding Guard")
+    process.on('uncaughtException', (err) => {
+        console.error(`\n💥 [INTERNAL CRASH]: ${err.message}`);
+        console.error(err.stack);
+        flushJournal('Uncaught Exception');
+        process.exit(1);
+    });
+
+    process.on('unhandledRejection', (reason) => {
+        console.error(`\n💥 [UNHANDLED REJECTION]: ${reason}`);
+        flushJournal('Unhandled Promise Rejection');
+        process.exit(1);
+    });
+}
+
+/**
+ * Update the journal reference during a batch operation.
+ * Use this to keep the halt handler pointed at the latest data.
+ * @param {Array} journalRef - Updated reference
+ */
+function updateJournalRef(journalRef) {
+    _journalRef = journalRef;
+}
+
+/**
+ * Clean shutdown — call after a batch completes successfully.
+ * Resets the halt handler state.
+ */
+function clearEmergencyHalt() {
+    _journalRef = null;
+    _isInitialized = false;
+}
+
+module.exports = { initEmergencyHalt, updateJournalRef, clearEmergencyHalt };

package/core/engine/apply-engine.js

@@ -0,0 +1,69 @@
+/**
+ * ═══════════════════════════════════════════════════════════════════
+ * FILEMAYOR v3.5 — APPLY ENGINE
+ * The Executioner: Reifies the Curative Plan into reality.
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+'use strict';
+
+const FileMayorFS = require('../fs-abstraction');
+
+class ApplyEngine {
+    constructor(options = {}) {
+        this.fs = new FileMayorFS(options);
+    }
+
+    /**
+     * Execute a validated Curative Plan
+     * @param {Object} plan - The plan from CureEngine
+     * @param {Object} progressCb - Optional progress callback
+     * @returns {Promise<Object>} Execution results
+     */
+    async apply(plan, progressCb = null) {
+        if (!plan || !Array.isArray(plan.plan)) {
+            throw new Error('Invalid plan: Nothing to apply.');
+        }
+
+        const stats = {
+            total: plan.plan.length,
+            success: 0,
+            failed: 0
+        };
+
+        for (let i = 0; i < plan.plan.length; i++) {
+            const step = plan.plan[i];
+            try {
+                await this.fs.move(step.source, step.destination);
+                stats.success++;
+                if (progressCb) progressCb({ 
+                    index: i + 1, 
+                    total: stats.total, 
+                    current: step.source,
+                    status: 'success'
+                });
+            } catch (err) {
+                stats.failed++;
+                if (progressCb) progressCb({ 
+                    index: i + 1, 
+                    total: stats.total, 
+                    current: step.source,
+                    status: 'error',
+                    error: err.message
+                });
+            }
+        }
+
+        return {
+            status: stats.failed === 0 ? 'completed' : 'partial',
+            stats,
+            journalCount: this.fs.getJournal().length
+        };
+    }
+
+    async rollback() {
+        return await this.fs.rollback();
+    }
+}
+
+module.exports = ApplyEngine;

package/core/engine/cure-engine.js

@@ -0,0 +1,70 @@
+/**
+ * ═══════════════════════════════════════════════════════════════════
+ * FILEMAYOR v3.5 — CURE ENGINE
+ * Orchestrates the Agent Crew to fix the clutter.
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+'use strict';
+
+const IntentStrategist = require('../ai/strategist');
+const MetadataSentry = require('../ai/sentry');
+const CurativePlanner = require('../ai/planner');
+const SecurityArchitect = require('../ai/validator');
+const { scan } = require('../scanner');
+
+class CureEngine {
+    constructor(dirPath, apiKey) {
+        // Smart detection: if dirPath looks like an API key (no path seps), swap args
+        if (dirPath && !apiKey && !dirPath.includes('/') && !dirPath.includes('\\') && dirPath.length > 20) {
+            this.apiKey = dirPath;
+            this.dirPath = null;
+        } else {
+            this.dirPath = dirPath;
+            this.apiKey = apiKey || process.env.GEMINI_API_KEY;
+        }
+        
+        this.strategist = new IntentStrategist();
+        this.sentry = new MetadataSentry();
+        this.planner = new CurativePlanner(this.apiKey);
+        this.architect = new SecurityArchitect();
+        
+        this.plan = null;
+    }
+
+    /**
+     * Perform curative operation (Brain phase) - UI Aligned
+     * @param {string} prompt - User intent
+     * @param {Function} progressCallback - Optional progress reporter
+     * @returns {Promise<Object>} Safe Curative Plan
+     */
+    async generatePlan(prompt, progressCallback) {
+        if (progressCallback) progressCallback("Scanning filesystem context...");
+        const scanResult = scan(this.dirPath, { maxDepth: 10 });
+
+        if (progressCallback) progressCallback("Identifying functional domains & ancestry...");
+        const sentryData = this.sentry.analyze(scanResult.files);
+
+        if (progressCallback) progressCallback("Consulting Intuition Engine...");
+        const intent = this.strategist.classify(prompt);
+
+        if (progressCallback) progressCallback("Synthesizing structural plan...");
+        const curativePlan = await this.planner.plan(intent, sentryData, prompt);
+
+        if (progressCallback) progressCallback("Validating structural integrity...");
+        const safePlan = this.architect.validate(curativePlan, sentryData);
+
+        this.plan = safePlan;
+        return safePlan;
+    }
+
+    /**
+     * Legacy entry point for CLI
+     */
+    async curate(dirPath, prompt) {
+        this.dirPath = dirPath;
+        return await this.generatePlan(prompt);
+    }
+}
+
+module.exports = CureEngine;

package/core/engine/dedupe-engine.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const { scan, formatBytes } = require('../scanner');
+const crypto = require('crypto');
+const fs = require('fs');
+
+/**
+ * DedupeEngine — specialized engine for finding and removing duplicates
+ */
+class DedupeEngine {
+    constructor() {}
+
+    /**
+     * Find duplicates in a directory
+     * @param {string} dirPath 
+     * @returns {Object} Duplicate report
+     */
+    find(dirPath) {
+        const result = scan(dirPath, { maxDepth: 10 });
+        const map = new Map();
+        const duplicates = [];
+        let totalWasted = 0;
+
+        for (const file of result.files) {
+            // Heuristic-based match (size + name)
+            // In a real pro version, we might do checksums here, 
+            // but for a fast CLI, this is the "Viral" speed way.
+            const key = `${file.size}-${file.name}`;
+            if (map.has(key)) {
+                const original = map.get(key);
+                duplicates.push({
+                    original,
+                    duplicate: file
+                });
+                totalWasted += file.size;
+            } else {
+                map.set(key, file);
+            }
+        }
+
+        return {
+            path: dirPath,
+            sets: duplicates.length,
+            totalWasted,
+            totalWastedHuman: formatBytes(totalWasted),
+            duplicates
+        };
+    }
+
+    /**
+     * Remove duplicates based on a report
+     */
+    async clean(report) {
+        let deleted = 0;
+        let freed = 0;
+        const errors = [];
+
+        for (const set of report.duplicates) {
+            try {
+                fs.unlinkSync(set.duplicate.path);
+                deleted++;
+                freed += set.duplicate.size;
+            } catch (err) {
+                errors.push(`${set.duplicate.name}: ${err.message}`);
+            }
+        }
+
+        return {
+            deleted,
+            freed,
+            freedHuman: formatBytes(freed),
+            errors
+        };
+    }
+}
+
+module.exports = DedupeEngine;

package/core/engine/explain-engine.js

@@ -0,0 +1,114 @@
+/**
+ * ═══════════════════════════════════════════════════════════════════
+ * FILEMAYOR v3.5 — EXPLAIN ENGINE
+ * The Diagnostic UX: "The doctor for your filesystem."
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+'use strict';
+
+const { scan } = require('../scanner');
+const MetadataSentry = require('../ai/sentry');
+
+class ExplainEngine {
+    constructor() {
+        this.sentry = new MetadataSentry();
+    }
+
+    /**
+     * Run a diagnostic scan and return structured insights
+     * @param {string} dirPath - Directory to analyze
+     * @returns {Object} Diagnostic report
+     */
+    run(dirPath) {
+        // 1. Scan the directory
+        const scanResult = scan(dirPath, { maxDepth: 10 });
+        
+        // 2. Use MetadataSentry to get clusters
+        const sentryData = this.sentry.analyze(scanResult.files);
+
+        // 3. Find duplicates (by name and size as a simple heuristic)
+        const duplicates = this._findDuplicates(scanResult.files);
+
+        // 4. Generate insights from clusters
+        const insights = this._generateInsights(sentryData, duplicates);
+
+        const health = this._calculateHealth(sentryData, duplicates);
+
+        return {
+            title: 'FILEMAYOR DIAGNOSIS',
+            path: dirPath,
+            health,
+            summary: sentryData.summary,
+            clusters: sentryData.clusters,
+            duplicates: duplicates.length,
+            duplicateSize: duplicates.reduce((acc, f) => acc + f.size, 0),
+            insights
+        };
+    }
+
+    _findDuplicates(files) {
+        const seen = new Map();
+        const duplicates = [];
+
+        for (const f of files) {
+            const key = `${f.name}-${f.size}`;
+            if (seen.has(key)) {
+                duplicates.push(f);
+            } else {
+                seen.set(key, f);
+            }
+        }
+        return duplicates;
+    }
+
+    _generateInsights(data, duplicates) {
+        const insights = [];
+        const { clusters } = data;
+
+        if (clusters.screenshot && clusters.screenshot.count > 10) {
+            insights.push(`${clusters.screenshot.count} screenshots scattered in folder.`);
+        }
+        
+        if (clusters.executable && clusters.executable.count > 5) {
+            insights.push(`${clusters.executable.count} installers consuming space.`);
+        }
+
+        if (duplicates.length > 0) {
+            insights.push(`${duplicates.length} duplicate files detected.`);
+        }
+
+        if (clusters.archive && clusters.archive.count > 3) {
+            insights.push(`Multiple old ZIP/RAR archives identified.`);
+        }
+
+        return insights;
+    }
+
+    _calculateHealth(data, duplicates) {
+        const totalFiles = data.summary.totalFiles;
+        if (totalFiles === 0) return { score: 100, label: 'EXCELLENT', color: '#10b981' };
+
+        // Deduction logic
+        let deductions = 0;
+        deductions += Math.min(30, (duplicates.length / totalFiles) * 100);
+        deductions += Math.min(30, (data.summary.categories.length > 8 ? 20 : 0)); // too many categories in one place
+        
+        const score = Math.max(0, 100 - Math.round(deductions));
+        
+        let label = 'GOOD';
+        let color = '#10b981';
+
+        if (score < 40) {
+            label = 'POOR';
+            color = '#ef4444';
+        } else if (score < 75) {
+            label = 'FAIR';
+            color = '#f59e0b';
+        }
+
+        return { score, label, color };
+    }
+}
+
+module.exports = ExplainEngine;

package/core/engine/preview-engine.js

@@ -0,0 +1,49 @@
+/**
+ * ═══════════════════════════════════════════════════════════════════
+ * FILEMAYOR v3.5 — PREVIEW ENGINE
+ * Formats Curative Plans for visualization.
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+'use strict';
+
+class PreviewEngine {
+    /**
+     * Format a plan for CLI display
+     * @param {Object} plan 
+     */
+    showInConsole(plan) {
+        console.log('\n--- CURATIVE PLAN PREVIEW ---');
+        console.log(`\nNARRATIVE: ${plan.narrative || 'No explanation provided.'}`);
+        console.log(`CONFIDENCE: ${plan.confidence || 0}%`);
+        
+        console.log('\nPROPOSED MOVES:');
+        if (plan.plan.length === 0) {
+            console.log(' (No changes suggested)');
+        } else {
+            plan.plan.forEach((step, idx) => {
+                console.log(` [${idx + 1}] ${step.source}`);
+                console.log(`     → ${step.destination}`);
+                console.log(`     Reason: ${step.reason || 'Organizing'}`);
+            });
+        }
+        
+        console.log(`\nTotal actions: ${plan.plan.length}`);
+        console.log('Run with `apply` to execute these changes.');
+        console.log('-----------------------------\n');
+    }
+
+    /**
+     * Format a plan for UI digestion
+     * @param {Object} plan 
+     */
+    formatForUI(plan) {
+        return {
+            ...plan,
+            timestamp: Date.now(),
+            summary: `${plan.plan.length} files to move`
+        };
+    }
+}
+
+module.exports = PreviewEngine;