filemayor 2.1.0 → 3.6.0

package/README.md

@@ -4,7 +4,7 @@
 # FileMayor
 ### The intelligent, local-first engine for filesystem order.
 
-`v2.1.0` · Windows · macOS · Linux · Node ≥18 · **Zero Dependencies**
+`v3.0.0` · Windows · macOS · Linux · Node ≥18 · **Zero Dependencies**
 
 [Website](https://filemayor.com) · [npm](https://www.npmjs.com/package/filemayor) · [Safety Report](#security)
 

package/core/ai/planner.js

@@ -0,0 +1,42 @@
+/**
+ * ═══════════════════════════════════════════════════════════════════
+ * FILEMAYOR AGENTIC CREW — CURATIVE PLANNER
+ * The Generative Brain (Gemini). Orchestrates the move plan.
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+'use strict';
+
+const IntentInterpreter = require('../intent-interpreter');
+
+class CurativePlanner {
+    constructor(apiKey) {
+        this.interpreter = new IntentInterpreter(apiKey);
+    }
+
+    /**
+     * Create a Curative Plan using AI logic
+     * @param {Object} intent - From Strategist
+     * @param {Object} sentryData - From MetadataSentry
+     * @param {string} rawPrompt - Original user input
+     * @returns {Promise<Object>} Curative Plan
+     */
+    async plan(intent, sentryData, rawPrompt) {
+        // v3.2 Intuition: Pass enriched clusters with relational metadata
+        const context = {
+            intent: intent.intent,
+            strategy: intent.strategy,
+            isRefine: intent.isRefine,
+            cwd: process.cwd()
+        };
+
+        // Standardized Bridge: Telemetry is passed as clusters
+        return await this.interpreter.interpret(
+            rawPrompt,
+            sentryData.clusters, 
+            context
+        );
+    }
+}
+
+module.exports = CurativePlanner;

package/core/ai/sentry.js

@@ -0,0 +1,92 @@
+/**
+ * ═══════════════════════════════════════════════════════════════════
+ * FILEMAYOR AGENTIC CREW — METADATA SENTRY
+ * Responsible for scanning, clustering, and summarizing filesystem state.
+ * Reduces token cost by 90% via representative sampling.
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+'use strict';
+
+const path = require('path');
+const crypto = require('crypto');
+
+class MetadataSentry {
+    /**
+     * Clustered Analysis: Group files by category and provided samples
+     * Now includes v3.2 Intuition metadata (Ancestry & Bundles)
+     * @param {Object[]} files - Raw FileInfo objects from scanner
+     * @returns {Object} Summarized perspective for the planner
+     */
+    analyze(files) {
+        const clusters = {};
+        const bundles = new Map(); // UUID map for Atomic Bundles
+        let totalBytes = 0;
+
+        // Pass 1: Dependency Mapping (Detect Anchors)
+        const ANCHORS = ['.git', '.als', '.flp', '.xcodeproj', 'package.json', 'index.js', 'project.json'];
+        
+        for (const f of files) {
+            if (!f.path) continue; // Skip files without a path
+            const fileName = path.basename(f.path).toLowerCase();
+            if (ANCHORS.includes(fileName) || ANCHORS.some(a => fileName.endsWith(a))) {
+                const bundlePath = path.dirname(f.path);
+                const bundleId = crypto.randomUUID();
+                bundles.set(bundlePath, bundleId);
+            }
+        }
+
+        // Pass 2: Analysis & Contextual Tagging
+        for (const f of files) {
+            const cat = f.category || 'other';
+            if (!clusters[cat]) {
+                clusters[cat] = {
+                    count: 0,
+                    totalSize: 0,
+                    samples: []
+                };
+            }
+
+            clusters[cat].count++;
+            clusters[cat].totalSize += f.size || 0;
+            totalBytes += f.size || 0;
+
+            // v3.2 Intuition: Build Ancestry (Depth 3)
+            const filePath = f.path || f.name || '';
+            const parts = filePath.split(/[\\/]/);
+            const ancestry = parts.length > 4 ? parts.slice(-4, -1) : parts.slice(0, -1);
+
+            // v3.2 Intuition: Resolve Bundle affinity
+            let bundleId = null;
+            for (const [bPath, bId] of bundles.entries()) {
+                if (filePath.startsWith(bPath)) {
+                    bundleId = bId;
+                    break;
+                }
+            }
+
+            // Keep only a few samples per category to save tokens
+            if (clusters[cat].samples.length < 5) {
+                clusters[cat].samples.push({
+                    name: f.name,
+                    path: f.path,
+                    ext: path.extname(f.name),
+                    ancestry,
+                    bundleId
+                });
+            }
+        }
+
+        return {
+            summary: {
+                totalFiles: files.length,
+                totalSize: totalBytes,
+                categories: Object.keys(clusters),
+                bundleCount: bundles.size
+            },
+            clusters
+        };
+    }
+}
+
+module.exports = MetadataSentry;

package/core/ai/strategist.js

@@ -0,0 +1,186 @@
+/**
+ * ═══════════════════════════════════════════════════════════════════
+ * FILEMAYOR AGENTIC CREW — INTENT STRATEGIST
+ * 
+ * Universal domain-aware intent classification.
+ * Detects folder "archetypes" from filenames, extensions, and
+ * directory names — then maps to the optimal organization strategy.
+ * 
+ * Supports: Music Production, Civics/Law, Agri-Tech, Business,
+ *           Technical/Code, Library, and General Archive.
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+'use strict';
+
+const path = require('path');
+
+// ─── Domain Archetype Definitions ─────────────────────────────────
+
+const ARCHETYPES = {
+    production: {
+        label: 'Music Production',
+        extSignals: ['.wav', '.mp3', '.flac', '.als', '.flp', '.mid', '.aif', '.ogg', '.aac', '.stem'],
+        nameSignals: ['_v1', '_v2', '_final', '_master', '_mix', 'stem', 'beat', 'vocal', 'inst'],
+        strategy: 'atomic_bundle_preservation',
+        hierarchy: 'Project Name → Stems / Masters / Project Files'
+    },
+    civics: {
+        label: 'Civics & Law (RSA)',
+        extSignals: ['.pdf', '.docx', '.doc', '.odt', '.jpg', '.png'],
+        nameSignals: ['sars', 'gazette', 'court', 'affidavit', 'invoice', 'contract', 'act_',
+            'regulation', 'compliance', 'permit', 'certificate', 'agsa', 'pfma', 'sca',
+            'judgment', 'bill', 'irp5', 'it3a', 'green_paper', 'white_paper', 'audit_report',
+            'fica', 'cipc', 'bbbee', 'labour_', 'municipal'],
+        strategy: 'entity_year_doctype',
+        hierarchy: 'Authority → Year → Document Type',
+        folders: ['01_Legislation', '02_Compliance', '03_Oversight', '04_Judiciary']
+    },
+    agritech: {
+        label: 'Agri-Tech (Farm)',
+        extSignals: ['.csv', '.xlsx', '.xls', '.tsv'],
+        nameSignals: ['tag_', 'vet_', 'herd', 'cattle', 'livestock', 'feed', 'breed',
+            'pasture', 'dip_', 'auction', 'kraal', 'bovine', 'vaccination', 'fmd',
+            'brucella', 'deworming', 'weaner', 'heifer', 'bull_', 'calf_', 'stud_',
+            'transport_permit', 'movement_permit', 'feedlot'],
+        strategy: 'category_datestamp',
+        hierarchy: 'Livestock Category → Date-Stamped Logs',
+        folders: ['Inventory', 'Health', 'Logistics']
+    },
+    business: {
+        label: 'Business',
+        extSignals: ['.pdf', '.png', '.jpg', '.xlsx'],
+        nameSignals: ['invoice_', 'receipt', 'quotation', 'po_', 'statement', 'expense', 'tax_', 'vat', 'payslip', 'order_'],
+        strategy: 'quarter_vendor_status',
+        hierarchy: 'Quarter → Vendor → Status'
+    },
+    technical: {
+        label: 'Technical / Code',
+        extSignals: ['.js', '.ts', '.py', '.go', '.rs', '.java', '.cpp', '.c', '.h', '.json', '.yaml', '.yml', '.toml', '.env', '.sh'],
+        nameSignals: ['config', 'test_', '_spec', 'build', 'deploy', 'docker', 'readme', 'license', 'makefile'],
+        strategy: 'substrate_preservation',
+        hierarchy: 'Project Root → src / tests / config / docs'
+    },
+    library: {
+        label: 'Library / Reference',
+        extSignals: ['.pdf', '.epub', '.mobi', '.djvu'],
+        nameSignals: ['book', 'chapter', 'isbn', 'edition', 'vol_', 'author'],
+        strategy: 'ancestry_matching',
+        hierarchy: 'Genre / Subject → Author → Title'
+    }
+};
+
+class IntentStrategist {
+    /**
+     * Classify user intent from a prompt string.
+     * Uses keyword matching for fast, local classification.
+     */
+    classify(prompt, context = {}) {
+        const p = prompt.toLowerCase();
+        let strategy = 'clustering';
+        let intent = 'organize';
+        let archetype = null;
+
+        const isRefine = p.includes('refine') || p.includes('structure') || p.includes('within');
+
+        if (p.includes('clean') || p.includes('space') || p.includes('junk')) {
+            intent = 'cleanup';
+            strategy = 'retention';
+        } else if (p.includes('tax') || p.includes('invoice') || p.includes('receipt')) {
+            intent = 'financial_sorting';
+            strategy = 'deep_scan';
+            archetype = 'business';
+        } else if (p.includes('music') || p.includes('stem') || p.includes('production') || p.includes('beat')) {
+            intent = 'music_production';
+            strategy = 'atomic_bundle_preservation';
+            archetype = 'production';
+        } else if (p.includes('book') || p.includes('library') || p.includes('read')) {
+            intent = 'library_curation';
+            strategy = 'ancestry_matching';
+            archetype = 'library';
+        } else if (p.includes('farm') || p.includes('cattle') || p.includes('herd') || p.includes('livestock')) {
+            intent = 'agritech_management';
+            strategy = 'category_datestamp';
+            archetype = 'agritech';
+        } else if (p.includes('law') || p.includes('legal') || p.includes('court') || p.includes('compliance')) {
+            intent = 'civics_filing';
+            strategy = 'entity_year_doctype';
+            archetype = 'civics';
+        } else if (p.includes('code') || p.includes('project') || p.includes('repo')) {
+            intent = 'codebase_org';
+            strategy = 'substrate_preservation';
+            archetype = 'technical';
+        }
+
+        return {
+            intent,
+            strategy,
+            isRefine,
+            archetype: archetype ? ARCHETYPES[archetype] : null,
+            rules: {
+                lockBundles: true,
+                respectAncestry: true,
+                depthLimit: 3
+            }
+        };
+    }
+
+    /**
+     * Detect the folder archetype from file metadata (zero-content).
+     * Scores each archetype by counting matching extension and name signals.
+     * Includes "Parental Hint" — the directory name itself influences scoring.
+     * 
+     * @param {Array} files - Array of { name, ext?, size? }
+     * @param {string} [folderName] - Name of the parent directory (parental hint)
+     * @returns {{ archetype: string, label: string, confidence: number, strategy: string }}
+     */
+    detectArchetype(files, folderName = '') {
+        const scores = {};
+        const folderHint = (folderName || '').toLowerCase();
+
+        for (const [key, arch] of Object.entries(ARCHETYPES)) {
+            let score = 0;
+
+            for (const file of files) {
+                const name = (file.name || '').toLowerCase();
+                const ext = (file.ext || path.extname(name)).toLowerCase();
+
+                // Extension match
+                if (arch.extSignals.includes(ext)) score += 2;
+
+                // Name signal match
+                for (const signal of arch.nameSignals) {
+                    if (name.includes(signal)) score += 3;
+                }
+            }
+
+            // Parental hint bonus (directory name contains archetype keywords)
+            for (const signal of arch.nameSignals) {
+                if (folderHint.includes(signal)) score += 5;
+            }
+
+            scores[key] = score;
+        }
+
+        // Find the winner
+        const sorted = Object.entries(scores).sort((a, b) => b[1] - a[1]);
+        const [topKey, topScore] = sorted[0];
+        const totalSignals = Object.values(scores).reduce((a, b) => a + b, 0);
+        const confidence = totalSignals > 0 ? Math.round((topScore / totalSignals) * 100) : 0;
+
+        if (topScore === 0) {
+            return { archetype: 'general', label: 'General / Mixed', confidence: 0, strategy: 'clustering' };
+        }
+
+        const arch = ARCHETYPES[topKey];
+        return {
+            archetype: topKey,
+            label: arch.label,
+            confidence,
+            strategy: arch.strategy,
+            hierarchy: arch.hierarchy
+        };
+    }
+}
+
+module.exports = IntentStrategist;

package/core/ai/validator.js

@@ -0,0 +1,116 @@
+/**
+ * ═══════════════════════════════════════════════════════════════════
+ * FILEMAYOR AGENTIC CREW — SECURITY ARCHITECT
+ * Deterministic validator. Never trusts AI output.
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+'use strict';
+
+const { isFileSafe, validatePath } = require('../security');
+const os = require('os');
+
+class SecurityArchitect {
+    constructor() {
+        // Dynamically resolve home directory parts for path normalization
+        const homeParts = os.homedir().toLowerCase().replace(/\\/g, '/').split('/').filter(x => x.length > 0);
+        this._homePrefixParts = new Set(homeParts); // e.g. Set{'c:', 'users', 'hloni'}
+    }
+
+    /**
+     * Final validation of an AI-generated plan
+     * @param {Object} plan - The Curative Plan from Planner
+     * @param {Object} sentryData - The ground-truth telemetry
+     * @returns {Object} Validated/Sanitized Plan
+     */
+    validate(plan, sentryData) {
+        if (!plan || !Array.isArray(plan.plan)) {
+            return { ...plan, plan: [], status: 'invalid' };
+        }
+
+        const domainTriggerFolders = ['books', 'library', 'projects', 'music', 'work', 'downloads'];
+        const clusters = sentryData?.clusters || {};
+        const allSamples = Object.values(clusters).flatMap(c => c.samples || []);
+        const homeParts = this._homePrefixParts;
+
+        // Robust Normalizer: strips drive letter and home dir parts, leaving only domain-relevant segments
+        const normalize = (p) => {
+            if (!p) return [];
+            return p.toLowerCase()
+                .replace(/\\/g, '/')
+                .split('/')
+                .filter(x => x.length > 0 && !homeParts.has(x));
+        };
+
+        const safeSteps = plan.plan.filter(step => {
+            try {
+                if (!step.source || !step.destination) return false;
+
+                const srcCheck = isFileSafe(step.source);
+                if (!srcCheck.safe) return false;
+
+                // 1. Domain Preservation (Rule of Ancestry)
+                const srcParts = normalize(step.source);
+                const destParts = normalize(step.destination);
+
+                const triggerFound = srcParts.find(p => domainTriggerFolders.includes(p));
+
+                if (triggerFound) {
+                    // A move is valid if the EXACT trigger folder is present in the destination path
+                    const preserved = destParts.includes(triggerFound);
+
+                    if (!preserved && !step.reason.includes('COLLECTION_MOVE')) {
+                        console.warn(`[ARCHITECTURE] Blocked domain scattering for ${step.source} -> ${step.destination}`);
+                        return false; 
+                    }
+                }
+
+                // 2. Atomic Bundle Lock
+                const sourceMeta = allSamples.find(s => s.path === step.source);
+                if (sourceMeta && sourceMeta.bundleId) {
+                    const bundleId = sourceMeta.bundleId;
+                    const bundleMembers = allSamples.filter(s => s.bundleId === bundleId);
+                    const planMembers = plan.plan.filter(s => {
+                        const meta = allSamples.find(m => m.path === s.source);
+                        return meta && meta.bundleId === bundleId;
+                    });
+
+                    // If not all members are moving, it's a split.
+                    if (planMembers.length < bundleMembers.length) {
+                        console.warn(`[ARCHITECTURE] Blocked bundle split for ${step.source} (Bundle: ${bundleId})`);
+                        return false;
+                    }
+
+                    // Ensure all members are going to the same parent domain
+                    const firstDestParts = normalize(planMembers[0].destination);
+                    const bundleDestRoot = firstDestParts.slice(0, -1).join('/');
+                    
+                    const matches = planMembers.every(s => {
+                        const dParts = normalize(s.destination);
+                        const dRoot = dParts.slice(0, -1).join('/');
+                        return dRoot === bundleDestRoot;
+                    });
+
+                    if (!matches) {
+                        console.warn(`[ARCHITECTURE] Blocked bundle scattering for ${step.source}`);
+                        return false;
+                    }
+                }
+
+                return true;
+            } catch (err) {
+                console.error('[ARCHITECTURE] Validation Error:', err);
+                return false;
+            }
+        });
+
+        return {
+            ...plan,
+            plan: safeSteps,
+            validatedCount: safeSteps.length,
+            status: safeSteps.length > 0 ? 'safe' : 'blocked'
+        };
+    }
+}
+
+module.exports = SecurityArchitect;

package/core/analyzer.js

@@ -76,15 +76,26 @@ function analyzeDirectory(dirPath, options = {}) {
             }
         }
     }
-
-    // 3. Bloat Mapping (Top Directories)
+    // 3. Bloat Mapping (Top Directories) & Progress Reporting
     const dirMap = new Map();
-    for (const file of files) {
+    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 i = 0; i < Math.min(parts.length - 1, 2); i++) {
-            currentPath = currentPath ? path.join(currentPath, parts[i]) : parts[i];
+        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 });
             }

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;