filemayor 2.1.0 → 3.6.0

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;

package/core/fs-abstraction.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+
+/**
+ * ═══════════════════════════════════════════════════════════════════
+ * FILEMAYOR FS v3.0 — INTENT-READY FILESYSTEM ABSTRACTION
+ * Async, safe, transactional, and fully rollbackable.
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+'use strict';
+
+const fs = require('fs').promises;
+const fssync = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+const { validatePath, isFileSafe, isDirSafe, canRead, canWrite } = require('./security');
+const { formatBytes } = require('./scanner');
+
+class FileMayorFS {
+    constructor(options = {}) {
+        this.options = {
+            useJournal: true,
+            dryRun: false,
+            trashPath: path.join(os.tmpdir(), 'filemayor_trash'),
+            journalPath: path.join(os.homedir(), '.filemayor-master-journal.json'),
+            ...options
+        };
+        this.sessionJournal = [];
+        this.stats = {
+            opsSucceeded: 0,
+            opsFailed: 0,
+            totalBytesProcessed: 0,
+            filesMoved: 0,
+            filesDeleted: 0
+        };
+        fssync.mkdirSync(this.options.trashPath, { recursive: true });
+    }
+
+    /** ------------------------
+     * Enhanced Snapshot
+     * -------------------------*/
+    async createSnapshot(filePath) {
+        try {
+            const stats = await fs.stat(filePath);
+            return {
+                path: filePath,
+                size: stats.size,
+                mtime: stats.mtimeMs,
+                hash: crypto.createHash('sha256').update(filePath + stats.mtimeMs).digest('hex')
+            };
+        } catch {
+            return { path: filePath };
+        }
+    }
+
+    /** ------------------------
+     * Async Move
+     * -------------------------*/
+    async move(source, destination) {
+        const result = { source, destination, action: 'move', status: 'pending' };
+
+        const sourceCheck = isFileSafe(source);
+        if (!sourceCheck.safe) throw new Error(`Source unsafe: ${sourceCheck.reason}`);
+
+        const destValidation = validatePath(destination);
+        if (!destValidation.valid) throw new Error(`Destination invalid: ${destValidation.error}`);
+
+        const snapshot = await this.createSnapshot(source);
+
+        if (this.options.dryRun) {
+            result.status = 'dry-run';
+            return result;
+        }
+
+        try {
+            const destDir = path.dirname(destination);
+            await fs.mkdir(destDir, { recursive: true });
+
+            try {
+                await fs.rename(source, destination);
+            } catch (err) {
+                if (err.code === 'EXDEV') {
+                    await fs.copyFile(source, destination);
+                    await fs.unlink(source);
+                } else throw err;
+            }
+
+            result.status = 'success';
+            this.stats.opsSucceeded++;
+            this.stats.filesMoved++;
+            this.stats.totalBytesProcessed += snapshot.size || 0;
+            await this._logToJournal(source, destination, 'move', snapshot);
+
+        } catch (err) {
+            result.status = 'error';
+            result.error = err.message;
+            this.stats.opsFailed++;
+            throw err;
+        }
+
+        return result;
+    }
+
+    /** ------------------------
+     * Safe Delete with Trash
+     * -------------------------*/
+    async delete(target) {
+        const check = isFileSafe(target);
+        if (!check.safe) throw new Error(`Target unsafe: ${check.reason}`);
+
+        const snapshot = await this.createSnapshot(target);
+
+        if (this.options.dryRun) return { target, status: 'dry-run' };
+
+        const trashFile = path.join(this.options.trashPath, path.basename(target) + '-' + Date.now());
+        await fs.rename(target, trashFile);
+
+        this.stats.opsSucceeded++;
+        this.stats.filesDeleted++;
+        this.stats.totalBytesProcessed += snapshot.size || 0;
+
+        await this._logToJournal(target, trashFile, 'delete', snapshot);
+
+        return { target, status: 'success' };
+    }
+
+    /** ------------------------
+     * Journaling
+     * -------------------------*/
+    async _logToJournal(source, destination, action, snapshot) {
+        if (!this.options.useJournal) return;
+
+        const entry = {
+            id: crypto.randomUUID(),
+            timestamp: new Date().toISOString(),
+            action,
+            source,
+            destination,
+            snapshot
+        };
+
+        this.sessionJournal.push(entry);
+
+        // Persistent Journaling (v3.5)
+        try {
+            let diskJournal = [];
+            if (fssync.existsSync(this.options.journalPath)) {
+                diskJournal = JSON.parse(fssync.readFileSync(this.options.journalPath, 'utf8'));
+            }
+            diskJournal.push(entry);
+            // Save last 1000 ops globally
+            fssync.writeFileSync(this.options.journalPath, JSON.stringify(diskJournal.slice(-1000), null, 2));
+        } catch (err) {
+            console.error(`[FAIL] Disk Journal write failed: ${err.message}`);
+        }
+    }
+
+    /** ------------------------
+     * Rollback
+     * -------------------------*/
+    async rollback() {
+        // Use session journal if available, otherwise try to load from disk
+        let reversed = [...this.sessionJournal].reverse();
+        
+        if (reversed.length === 0 && fssync.existsSync(this.options.journalPath)) {
+            console.log(`[SYS] Session journal empty. Attempting disk rollback...`);
+            const diskJournal = JSON.parse(fssync.readFileSync(this.options.journalPath, 'utf8'));
+            reversed = diskJournal.reverse();
+        }
+
+        console.log(`[SYS] Rolling back ${reversed.length} operations...`);
+
+        for (const entry of reversed) {
+            try {
+                if (entry.action === 'move') {
+                    if (fssync.existsSync(entry.destination)) {
+                        await fs.rename(entry.destination, entry.source);
+                    }
+                } else if (entry.action === 'delete') {
+                    if (fssync.existsSync(entry.destination)) {
+                        await fs.rename(entry.destination, entry.source);
+                    }
+                }
+            } catch (err) {
+                console.error(`[FAIL] Rollback failed for ${entry.source}: ${err.message}`);
+            }
+        }
+
+        this.sessionJournal = [];
+        console.log(`[SYS] Rollback complete.`);
+    }
+
+    getJournal() {
+        return this.sessionJournal;
+    }
+}
+
+module.exports = FileMayorFS;

package/core/guardrail.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+/**
+ * ═══════════════════════════════════════════════════════════════════
+ * FILEMAYOR CORE — LOGIC GUARDRAIL
+ * 
+ * The final layer of the Chevza Doctrine: INTENTIONALITY.
+ * Sits between the AI Intuition Engine and the Jailer.
+ * Forces a dry-run preview + user confirmation for high-volume
+ * or destructive-pattern operations.
+ * 
+ * Zero-dependency: uses native `readline/promises`.
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+'use strict';
+
+const readline = require('readline/promises');
+const { stdin: input, stdout: output } = require('process');
+const path = require('path');
+
+class LogicGuardrail {
+    /**
+     * @param {number} safetyLimit - Max ops before triggering confirmation (default: 50)
+     */
+    constructor(safetyLimit = 50) {
+        this.safetyLimit = safetyLimit;
+    }
+
+    /**
+     * Analyze a batch plan and require user confirmation if suspicious.
+     * @param {Array} batch - Array of { source, destination, type?, reason? }
+     * @returns {Promise<boolean>} Whether the user approved the batch
+     */
+    async verifyBatch(batch) {
+        if (!Array.isArray(batch) || batch.length === 0) return true;
+
+        const operationCount = batch.length;
+
+        // Auto-pass for small, safe batches
+        if (operationCount < this.safetyLimit && !this.isDestructivePattern(batch)) {
+            return true;
+        }
+
+        // ─── Dry Run Summary ─────────────────────────────────────
+        console.log('\n' + '═'.repeat(60));
+        console.log('⚠️  [LOGIC GUARDRAIL] High-Volume Operation Detected');
+        console.log('═'.repeat(60));
+        console.log(`   Total operations: ${operationCount}`);
+        console.log(`   Safety limit:     ${this.safetyLimit}`);
+
+        if (this.isDestructivePattern(batch)) {
+            console.log('\n   🔴 WARNING: Destructive pattern detected!');
+            console.log('   Many files are being moved to a single destination.');
+            console.log('   This could indicate an AI "Semantic Wipe" or "Over-Organizer" loop.');
+        }
+
+        // Show preview of first 5 operations
+        console.log('\n   Preview:');
+        const preview = batch.slice(0, 5);
+        for (const op of preview) {
+            const srcName = path.basename(op.source || '');
+            const dstDir = path.dirname(op.destination || '');
+            console.log(`   ${srcName} → ${dstDir}`);
+        }
+        if (operationCount > 5) {
+            console.log(`   ... and ${operationCount - 5} more.`);
+        }
+        console.log('═'.repeat(60));
+
+        // ─── User Confirmation (Native Node.js) ─────────────────
+        const rl = readline.createInterface({ input, output });
+        try {
+            const answer = await rl.question('\n   Proceed with this batch? (y/N): ');
+            return answer.toLowerCase().trim() === 'y';
+        } finally {
+            rl.close();
+        }
+    }
+
+    /**
+     * Detect if the AI is funneling many files into a single destination.
+     * This catches "Over-Organizer Loops" and "Semantic Wipes."
+     * @param {Array} batch - The operation batch
+     * @returns {boolean} True if the pattern looks destructive
+     */
+    isDestructivePattern(batch) {
+        if (batch.length < 10) return false;
+
+        const destDirs = batch.map(b => {
+            const dest = b.destination || '';
+            return path.dirname(dest).toLowerCase();
+        });
+        const uniqueDests = new Set(destDirs).size;
+
+        // If 10+ files all going to 1 directory, it's suspicious
+        return (batch.length / uniqueDests) > 10;
+    }
+
+    /**
+     * Detect "Nesting Hell" — AI creating deeply nested structures
+     * @param {Array} batch - The operation batch
+     * @param {number} maxDepth - Maximum allowed nesting depth (default: 8)
+     * @returns {Array} Entries that exceed the nesting depth
+     */
+    detectNestingHell(batch, maxDepth = 8) {
+        return batch.filter(op => {
+            const dest = op.destination || '';
+            const segments = dest.replace(/\\/g, '/').split('/').filter(s => s.length > 0);
+            return segments.length > maxDepth;
+        });
+    }
+}
+
+module.exports = LogicGuardrail;