filemayor 2.1.0 → 3.6.0

package/core/index.js

@@ -11,6 +11,8 @@
 
 const scanner = require('./scanner');
 const organizer = require('./organizer');
+const IntentInterpreter = require('./intent-interpreter');
+const FileMayorFS = require('./fs-abstraction');
 const cleaner = require('./cleaner');
 const watcher = require('./watcher');
 const config = require('./config');
@@ -18,6 +20,22 @@ const reporter = require('./reporter');
 const categories = require('./categories');
 const security = require('./security');
 const sopParser = require('./sop-parser');
+const analyzer = require('./analyzer');
+const license = require('./license');
+const ExplainEngine = require('./engine/explain-engine');
+const CureEngine = require('./engine/cure-engine');
+const ApplyEngine = require('./engine/apply-engine');
+const PreviewEngine = require('./engine/preview-engine');
+const DedupeEngine = require('./engine/dedupe-engine');
+const MetadataStore = require('./metadata-store');
+const strategist = require('./ai/strategist');
+const sentry = require('./ai/sentry');
+const planner = require('./ai/planner');
+const validator = require('./ai/validator');
+const { FileMayorJailer, enforceUserSpace } = require('./jailer');
+const Vault = require('./vault');
+const LogicGuardrail = require('./guardrail');
+const { initEmergencyHalt, updateJournalRef, clearEmergencyHalt } = require('./emergency-halt');
 
 module.exports = {
     // Scanner
@@ -26,6 +44,7 @@ module.exports = {
     scanByCategory: scanner.scanByCategory,
     scanSummary: scanner.scanSummary,
     formatBytes: scanner.formatBytes,
+    analyzeDirectory: analyzer.analyzeDirectory,
 
     // Organizer
     organize: organizer.organize,
@@ -35,6 +54,12 @@ module.exports = {
     loadJournal: organizer.loadJournal,
     NAMING_CONVENTIONS: organizer.NAMING_CONVENTIONS,
 
+    // Intent Interpreter
+    IntentInterpreter: IntentInterpreter,
+
+    // FS Abstraction
+    FileMayorFS: FileMayorFS,
+
     // Cleaner
     Cleaner: cleaner.Cleaner,
     findJunk: cleaner.findJunk,
@@ -74,6 +99,37 @@ module.exports = {
     rulesToConfig: sopParser.rulesToConfig,
     FILE_TYPE_ALIASES: sopParser.FILE_TYPE_ALIASES,
 
+    // License
+    activateLicense: license.activateLicense,
+    deactivateLicense: license.deactivateLicense,
+    getLicenseInfo: license.getLicenseInfo,
+    checkProFeature: license.checkProFeature,
+    checkBulkLimit: license.checkBulkLimit,
+    hasFeature: license.hasFeature,
+
+    // Intent Agents
+    IntentStrategist: strategist,
+    MetadataSentry: sentry,
+    CurativePlanner: planner,
+    SecurityArchitect: validator,
+
+    // Engines
+    ExplainEngine,
+    CureEngine,
+    ApplyEngine,
+    PreviewEngine,
+    DedupeEngine,
+    MetadataStore,
+
+    // Hardened Runtime
+    FileMayorJailer,
+    enforceUserSpace,
+    Vault,
+    LogicGuardrail,
+    initEmergencyHalt,
+    updateJournalRef,
+    clearEmergencyHalt,
+
     // Version
     VERSION: require('../package.json').version || '2.0.0'
 };

package/core/intent-interpreter.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+
+/**
+ * ═══════════════════════════════════════════════════════════════════
+ * FILEMAYOR v3.0 — INTENT INTERPRETER
+ * AI Logic Layer: Bridges fuzzy human language and atomic execution.
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+'use strict';
+
+const path = require('path');
+
+const GEMINI_MODEL = 'gemini-2.0-flash';
+const GEMINI_ENDPOINT = `https://generativelanguage.googleapis.com/v1beta/models/${GEMINI_MODEL}:generateContent`;
+
+class IntentInterpreter {
+    constructor(apiKey) {
+        this.apiKey = apiKey || process.env.GEMINI_API_KEY;
+        if (!this.apiKey) {
+            console.warn('[WARN] GEMINI_API_KEY not found. AI features will be disabled.');
+        }
+    }
+
+    /**
+     * Interpret a user prompt against clustered telemetry
+     * @param {string} userPrompt
+     * @param {Object} clusters - From MetadataSentry
+     * @param {Object} context
+     * @returns {Promise<Object>} The Curative Plan
+     */
+    async interpret(userPrompt, clusters, context = {}) {
+        if (!this.apiKey) {
+            throw new Error('API Key missing. Cannot interpret intent.');
+        }
+
+        const telemetry = this._summarizeFiles(clusters);
+        const systemPrompt = this._getSystemPrompt(context);
+
+        const response = await this._callGemini(systemPrompt, userPrompt, telemetry);
+        const curativePlan = this._parseResponse(response);
+
+        // [Production Grade] Confidence Gating
+        if (curativePlan.confidence < 60) {
+            curativePlan.status = 'low_confidence';
+            curativePlan.message = 'I am not entirely sure about this request. Could you clarify your intent?';
+        }
+
+        // [Production Grade] Plan Validation
+        curativePlan.plan = this._validatePlan(curativePlan.plan);
+
+        return curativePlan;
+    }
+
+    /**
+     * Summarize clustered file list for AI ingestion
+     */
+    _summarizeFiles(clusters) {
+        const summary = {};
+        
+        for (const cat in clusters) {
+            summary[cat] = {
+                count: clusters[cat].count,
+                samples: clusters[cat].samples.map(s => ({
+                    name: s.name,
+                    path: s.path,
+                    ancestry: s.ancestry,
+                    bundleId: s.bundleId
+                }))
+            };
+        }
+        
+        return summary;
+    }
+
+    _getSystemPrompt(context) {
+        return `You are FileMayor v3.2, the "Intuition & Dependency Engine".
+Your goal is to organize files while strictly preserving the integrity of projects and collections.
+
+INPUT:
+1. User Intent: "${context.intent}" (Strategy: "${context.strategy}")
+2. Telemetry: Clustered file metadata including 'ancestry' and 'bundleId'.
+
+GOLDEN RULES:
+- RULE OF ANCESTRY: Respect parent directory names in 'ancestry'. If a file is in /Books/ or a project folder, DO NOT scatter it based on extension alone.
+- ATOMIC BUNDLING: Files sharing a 'bundleId' (like music stems with a project file) MUST stay together.
+- REFINE, DON'T DESTROY: A "Refine" intent means improving structure WITHIN a domain, not extracting files OUT of it. 
+- FORMAT: Return a VALID JSON object. Use absolute paths for source.
+
+OUTPUT SCHEMA:
+{
+  "narrative": "A curative explanation of the structural refinement.",
+  "plan": [
+    { "source": "absolute/path", "destination": "suggested/target", "reason": "Why?" }
+  ],
+  "confidence": 0-100
+}`;
+    }
+
+    async _callGemini(systemPrompt, userPrompt, files) {
+        const body = {
+            contents: [{
+                parts: [{
+                    text: `${systemPrompt}\n\nUSER INTENT: "${userPrompt}"\n\nFILES:\n${JSON.stringify(files, null, 2)}`
+                }]
+            }],
+            generationConfig: {
+                temperature: 0.1, // Even lower for higher determinism
+                topP: 0.95,
+                maxOutputTokens: 2048,
+                responseMimeType: "application/json" // [Production Grade] Force JSON Mode
+            }
+        };
+
+        const url = `${GEMINI_ENDPOINT}?key=${this.apiKey}`;
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+
+        if (!response.ok) {
+            const err = await response.text();
+            throw new Error(`Gemini API Error: ${response.status} - ${err}`);
+        }
+
+        const data = await response.json();
+        return data?.candidates?.[0]?.content?.parts?.[0]?.text || '';
+    }
+
+    /**
+     * Validate plan entries from AI response
+     * Filters out any entries missing required fields
+     */
+    _validatePlan(plan) {
+        if (!Array.isArray(plan)) return [];
+        return plan.filter(entry => {
+            if (!entry || typeof entry !== 'object') return false;
+            if (!entry.source || typeof entry.source !== 'string') return false;
+            if (!entry.destination || typeof entry.destination !== 'string') return false;
+            if (!entry.reason) entry.reason = 'AI suggested move';
+            return true;
+        });
+    }
+
+    _parseResponse(rawText) {
+        try {
+            const jsonMatch = rawText.match(/\{[\s\S]*\}/);
+            if (!jsonMatch) throw new Error('No JSON found in AI response');
+            return JSON.parse(jsonMatch[0]);
+        } catch (err) {
+            console.error('[FAIL] Failed to parse AI response:', rawText);
+            throw new Error(`AI Parsing Error: ${err.message}`);
+        }
+    }
+}
+
+module.exports = IntentInterpreter;

package/core/jailer.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+/**
+ * ═══════════════════════════════════════════════════════════════════
+ * FILEMAYOR CORE — THE JAILER (IMMUTABLE SECURITY LAYER)
+ * 
+ * This is the final firewall between FileMayor's AI "intuition" and
+ * the actual operating system. Even if Gemini suggests moving files
+ * into System32, this module kills the operation cold.
+ * 
+ * CRITICAL: This file must NEVER be modified by AI assistants.
+ * It is the immutable source of truth for filesystem safety.
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+// ─── Forbidden Zones (OS-Agnostic) ───────────────────────────────
+const FORBIDDEN_ZONES = [
+    // Windows
+    'C:\\Windows', 'C:\\Program Files', 'C:\\Program Files (x86)',
+    'C:\\ProgramData', 'C:\\Users\\Public', 'C:\\Users\\Default',
+    // Linux / macOS
+    '/etc', '/usr', '/bin', '/sbin', '/var', '/root',
+    '/boot', '/dev', '/proc', '/sys', '/run',
+    // macOS specific
+    '/System', '/Library', '/private'
+].map(p => path.resolve(p).toLowerCase());
+
+/**
+ * THE JAILER: Final security check for ALL FileMayor operations.
+ * Use this before ANY fs.rename, fs.unlink, or fs.copy operation.
+ */
+class FileMayorJailer {
+    /**
+     * @param {string} rootDirectory - The user's working directory (the "jail")
+     */
+    constructor(rootDirectory = process.cwd()) {
+        // Resolve the root to its absolute, REAL path (no symlinks)
+        try {
+            this.safeRoot = fs.realpathSync(path.resolve(rootDirectory)).toLowerCase();
+        } catch {
+            this.safeRoot = path.resolve(rootDirectory).toLowerCase();
+        }
+    }
+
+    /**
+     * Validate that a target path is safe for FileMayor to operate on.
+     * Resolves symlinks to their TRUE destination before checking.
+     * 
+     * @param {string} targetPath - The path to validate
+     * @returns {{ safe: boolean, realPath: string, error?: string }}
+     */
+    validate(targetPath) {
+        try {
+            if (!targetPath || typeof targetPath !== 'string') {
+                return { safe: false, realPath: '', error: 'Empty or invalid path' };
+            }
+
+            // Reject null bytes (classic injection vector)
+            if (targetPath.includes('\0')) {
+                return { safe: false, realPath: '', error: 'Null byte injection detected' };
+            }
+
+            const absoluteTarget = path.resolve(targetPath);
+
+            // [ANTI-SYMLINK] Resolve the REAL path (follows symlinks to true source)
+            // This defeats CVE-2025-55130 style symlink race conditions
+            let realTarget;
+            try {
+                realTarget = fs.existsSync(absoluteTarget)
+                    ? fs.realpathSync(absoluteTarget)
+                    : absoluteTarget;
+            } catch {
+                realTarget = absoluteTarget;
+            }
+
+            const normalizedTarget = realTarget.toLowerCase();
+
+            // [JAIL CHECK] Is the target inside our allowed project folder?
+            if (!normalizedTarget.startsWith(this.safeRoot + path.sep) &&
+                normalizedTarget !== this.safeRoot) {
+                return {
+                    safe: false,
+                    realPath: realTarget,
+                    error: `JAIL BREACH: "${realTarget}" is outside the safe root "${this.safeRoot}"`
+                };
+            }
+
+            // [SYSTEM CHECK] Is the target a protected OS zone?
+            for (const zone of FORBIDDEN_ZONES) {
+                if (normalizedTarget.startsWith(zone + path.sep) || normalizedTarget === zone) {
+                    return {
+                        safe: false,
+                        realPath: realTarget,
+                        error: `SYSTEM PROTECTION: "${realTarget}" is within forbidden zone "${zone}"`
+                    };
+                }
+            }
+
+            // [EXTENSION CHECK] Reject system-critical file types
+            const ext = path.extname(realTarget).toLowerCase();
+            const dangerousExts = new Set(['.sys', '.drv', '.dll', '.so', '.dylib', '.kext', '.plist', '.reg']);
+            if (dangerousExts.has(ext)) {
+                return {
+                    safe: false,
+                    realPath: realTarget,
+                    error: `DANGEROUS FILE: "${ext}" files are system-critical and cannot be moved`
+                };
+            }
+
+            return { safe: true, realPath: realTarget };
+
+        } catch (err) {
+            return { safe: false, realPath: '', error: `Jailer error: ${err.message}` };
+        }
+    }
+
+    /**
+     * Validate a move operation (both source AND destination must be safe)
+     * @param {string} source - Source file path
+     * @param {string} destination - Destination file path
+     * @returns {{ safe: boolean, error?: string }}
+     */
+    validateMove(source, destination) {
+        const srcCheck = this.validate(source);
+        if (!srcCheck.safe) return { safe: false, error: `Source: ${srcCheck.error}` };
+
+        const dstCheck = this.validate(destination);
+        if (!dstCheck.safe) return { safe: false, error: `Destination: ${dstCheck.error}` };
+
+        return { safe: true };
+    }
+}
+
+// ─── Root/Sudo Kill-Switch ────────────────────────────────────────
+// If running as root on Unix, exit immediately. FileMayor should
+// NEVER have elevated privileges to limit blast radius.
+function enforceUserSpace() {
+    if (typeof process.getuid === 'function' && process.getuid() === 0) {
+        console.error('❌ FILEMAYOR SECURITY ERROR: Running as root/sudo is strictly forbidden.');
+        console.error('   FileMayor is designed to run in User Space only.');
+        process.exit(1);
+    }
+}
+
+module.exports = { FileMayorJailer, enforceUserSpace, FORBIDDEN_ZONES };

package/core/license.js

@@ -66,10 +66,12 @@ const BUILTIN_KEYS = {
  * @returns {string} 5-char checksum
  */
 function generateChecksum(body) {
-    const hash = crypto.createHmac('sha256', CHECKSUM_SECRET)
-        .update(body)
-        .digest('hex');
-    return hash.substring(0, 5).toUpperCase();
+    // Ported from Admin Dashboard simpleHash for cross-platform compatibility
+    let hash = 0;
+    for (let i = 0; i < body.length; i++) {
+        hash = ((hash << 5) - hash + body.charCodeAt(i)) | 0;
+    }
+    return Math.abs(hash).toString(36).toUpperCase().padEnd(5, '0').substring(0, 5);
 }
 
 /**

package/core/metadata-store.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+
+/**
+ * ═══════════════════════════════════════════════════════════════════
+ * FILEMAYOR CORE — METADATA STORE
+ * Lightweight, persistent indexing for S2 compliance (<300ms search).
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+'use strict';
+
+const fs = require('fs').promises;
+const fssync = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+class MetadataStore {
+    constructor(dbPath) {
+        this.rootPath = dbPath || path.join(os.homedir(), '.filemayor', 'metadata_index.json');
+        this.index = {
+            version: '1.0',
+            lastUpdated: null,
+            files: {} // path -> metadata
+        };
+        this._ensureDir();
+        this.load();
+    }
+
+    _ensureDir() {
+        const dir = path.dirname(this.rootPath);
+        if (!fssync.existsSync(dir)) {
+            fssync.mkdirSync(dir, { recursive: true });
+        }
+    }
+
+    load() {
+        try {
+            if (fssync.existsSync(this.rootPath)) {
+                const data = fssync.readFileSync(this.rootPath, 'utf8');
+                this.index = JSON.parse(data);
+            }
+        } catch (err) {
+            console.error('[IDX] Failed to load index:', err.message);
+        }
+    }
+
+    async save() {
+        try {
+            this.index.lastUpdated = new Date().toISOString();
+            await fs.writeFile(this.rootPath, JSON.stringify(this.index, null, 2));
+        } catch (err) {
+            console.error('[IDX] Failed to save index:', err.message);
+        }
+    }
+
+    /**
+     * Update the index with fresh file metadata
+     * @param {Object[]} files 
+     */
+    update(files) {
+        for (const file of files) {
+            this.index.files[file.path] = {
+                name: file.name,
+                size: file.size,
+                mtime: file.modified,
+                category: file.category,
+                ext: file.ext
+            };
+        }
+    }
+
+    /**
+     * Search the index with < 300ms latency
+     * @param {string} query 
+     * @returns {Object[]}
+     */
+    search(query) {
+        const startTime = Date.now();
+        const results = [];
+        const lowerQuery = query.toLowerCase();
+
+        for (const [filePath, meta] of Object.entries(this.index.files)) {
+            if (meta.name.toLowerCase().includes(lowerQuery) || filePath.toLowerCase().includes(lowerQuery)) {
+                results.push({ path: filePath, ...meta });
+            }
+            if (results.length > 100) break; // Cap results for performance
+        }
+
+        const duration = Date.now() - startTime;
+        return {
+            results,
+            duration,
+            totalFound: results.length
+        };
+    }
+
+    clear() {
+        this.index.files = {};
+        this.save();
+    }
+}
+
+module.exports = new MetadataStore();