filemayor 2.1.0 → 4.0.5

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

@@ -1,152 +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)
-    const dirMap = new Map();
-    for (const file of files) {
-        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];
-            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
-};
+#!/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
+};