filemayor 2.0.5 → 3.6.0

package/README.md

@@ -1,84 +1,89 @@
 <div align="center">
+<img src="https://raw.githubusercontent.com/Hrypopo/filemayor-landing/main/logo.png" width="128" height="128" alt="FileMayor logo" />
 
 # FileMayor
+### The intelligent, local-first engine for filesystem order.
 
-**Organize, scan, clean, and watch your filesystem — from any terminal.**
+`v3.0.0` · Windows · macOS · Linux · Node ≥18 · **Zero Dependencies**
 
-`v2.0.1` · Windows · macOS · Linux · Node ≥18
+[Website](https://filemayor.com) · [npm](https://www.npmjs.com/package/filemayor) · [Safety Report](#security)
 
 </div>
 
 ---
 
+## Why FileMayor?
+
+Hacker News skeptics, we hear you. Why not `du`, `find`, or `ncdu`? 
+
+Unix tools are powerful but dangerous and manual. **FileMayor** provides a middle ground: **Recursive context-aware intelligence** paired with **Psychological Safety**. 
+
+- **Intelligence**: Don't just list files; analyze bloat, find duplicates across names, and auto-categorize into 12 smart categories.
+- **Safety**: Every move is journaled. Every destructive action is dry-run by default. Every mistake is reversible.
+
 ## Install
 
 ```bash
 npm install -g filemayor
 ```
 
-## Commands
+## Quick Start
 
 ```bash
-filemayor scan ~/Downloads              # See what's in a folder
-filemayor organize ~/Downloads          # Sort files into categories
-filemayor organize ~/Downloads --dry-run # Preview without moving
-filemayor clean /var/tmp --yes          # Delete junk files
-filemayor watch ~/Downloads             # Auto-organize in real-time
-filemayor undo ~/Downloads              # Undo last organization
-filemayor init                          # Create config file
-filemayor info                          # System info + version
-```
+# Get deep insights into your disk bloat and duplicate waste
+filemayor analyze ~/Downloads
+
+# Preview a massive organization change without touching a bit
+filemayor organize ~/Downloads --dry-run
 
-## What It Does
+# Reclaim space by nuking system junk and temporary rot
+filemayor clean /var/tmp --yes
 
-| Command | Description |
-|---------|-------------|
-| `scan` | Recursively scan directories — size, type, date filtering |
-| `organize` | Auto-sort files into 12 categories with undo journal |
-| `clean` | Detect and remove temp, cache, logs, system junk |
-| `watch` | Monitor folders in real-time with rules engine |
-| `undo` | Rollback any organization safely |
+# Restore order if you change your mind
+filemayor undo ~/Downloads
+```
 
-## 12 File Categories · 180+ Extensions
+## Features
 
-Documents · Images · Audio · Video · Archives · Code · Config · Fonts · Data · Executables · Design · Books
+- **`analyze` (New)**: Deep intelligence. Fhash-based duplicate detection, top directory bloat mapping, and potential savings calculation.
+- **`organize`**: Deterministic sorting into Documents, Images, Media, etc.
+- **`clean`**: Multi-category junk removal (temp, cache, logs, system, dependencies).
+- **`watch` (Pro)**: Real-time background organization using a high-performance rules engine.
+- **`undo`**: 100% cryptographic rollback of any organizational operation.
 
-## Output Formats
+## Security & Safety Protocols
 
-```bash
-filemayor scan . --json          # Machine-readable JSON
-filemayor scan . --csv > out.csv # Spreadsheet export
-filemayor scan . --minimal       # Paths only
-```
+We touch your files. We take that seriously.
+
+1.  **100% Local**: No telemetry. No cloud uploads. No API calls to remote servers. Your file names and structures never leave your RAM.
+2.  **Dry-Run by Default**: Organization commands require an explicit execution or a `--dry-run` preview.
+3.  **Rollback Journaling**: Every move is recorded in a local `.filemayor-journal.json`. The `undo` command uses this to restore your filesystem state perfectly.
+4.  **Supply-Chain Secured**: **Zero** runtime dependencies. No hidden npm vulnerabilities. No `node_modules` rot in production.
 
 ## Configuration
 
-Create `.filemayor.yml` in any directory:
+Control your engine with a simple `.filemayor.yml`:
 
 ```yaml
 organize:
-  naming: category_prefix    # original | category_prefix | date_prefix
-  duplicates: rename         # rename | skip | overwrite
-  ignore: [node_modules, .git, dist]
+  naming: category_prefix    # options: original | category_prefix | date_prefix | clean
+  duplicates: rename         # options: rename | skip | overwrite
+  ignore: [node_modules, .git, dist, build]
 
 watch:
   directories: [~/Downloads]
   rules:
     - match: "*.pdf"
       action: move
-      dest: ~/Documents/PDFs
+      dest: ~/Documents/Finance
 ```
 
-## Security
-
-- All processing is **100% local** — no data leaves your machine
-- Path traversal protection on all operations
-- System directory safeguards (won't touch OS files)
-- Zero runtime dependencies
-
-## License
+## Pricing
 
-Proprietary — see [LICENSE](LICENSE) for details.
+FileMayor is built by builders for builders.
+- **Free**: Core scanning, organization, cleaning, and undo.
+- **Pro**: Real-time Watch mode, AI-powered SOP parsing, and Bulk processing.
+- **Activation**: `filemayor license activate FM-PRO-XXXX`
 
 ---
 
@@ -86,6 +91,6 @@ Proprietary — see [LICENSE](LICENSE) for details.
 
 Created by **Lehlohonolo Goodwill Nchefu (Chevza)**
 
-[GitHub](https://github.com/Hrypopo) · [npm](https://www.npmjs.com/package/filemayor)
+Built for the builders who refuse to let digital rot win.
 
 </div>

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;