filemayor 2.1.0 → 3.6.0

package/core/security.js

@@ -27,7 +27,8 @@ const PROTECTED_DIRECTORIES = new Set([
 const PROTECTED_PREFIXES = [
     '/System', '/Library/System',
     'C:\\Windows', 'C:\\Program Files', 'C:\\Program Files (x86)',
-    'C:\\ProgramData', '/usr/lib', '/usr/bin', '/usr/sbin',
+    'C:\\ProgramData', 'C:\\Users\\Public',
+    '/usr/lib', '/usr/bin', '/usr/sbin',
     '/var/lib', '/var/run', '/boot', '/dev', '/proc', '/sys'
 ];
 
@@ -36,6 +37,14 @@ const DANGEROUS_EXTENSIONS = new Set([
     '.plist', '.reg', '.msc', '.cpl'
 ]);
 
+// ─── Project Substrates (v3.5) ────────────────────────────────────
+const SUBSTRATE_MARKERS = [
+    '.git', '.svn', 'node_modules', 'package.json',
+    'venv', '.venv', '__pycache__', 'env',
+    'pom.xml', 'build.gradle', 'CMakeLists.txt',
+    'Makefile', '.hg', 'composer.json', 'go.mod'
+];
+
 // ─── Path Validation ──────────────────────────────────────────────
 
 /**
@@ -49,27 +58,32 @@ function validatePath(inputPath, basePath = null) {
         return { valid: false, resolved: '', error: 'Path is empty or invalid' };
     }
 
-    // Reject null bytes (path traversal vector)
+    // [Hacker-Proof] Reject null bytes (classic path traversal vector)
     if (inputPath.includes('\0')) {
         return { valid: false, resolved: '', error: 'Path contains null bytes (rejected)' };
     }
 
-    // Resolve to absolute
+    // [Hacker-Proof] Resolve to absolute and normalize to handle '..' etc.
     const resolved = path.resolve(inputPath);
+    const rLower = resolved.toLowerCase();
 
-    // If a basePath is given, ensure resolved path stays within it
+    // [Hacker-Proof] Jail Logic: If a basePath is given, ensure resolved path stays within it
     if (basePath) {
-        const resolvedBase = path.resolve(basePath);
-        if (!resolved.startsWith(resolvedBase + path.sep) && resolved !== resolvedBase) {
+        const resolvedBase = path.resolve(basePath).toLowerCase();
+        
+        // [Elite Fix] Robust jailing: Target must start with base + separator or be the base itself
+        const isSafe = rLower === resolvedBase || rLower.startsWith(resolvedBase + path.sep);
+        
+        if (!isSafe) {
             return {
                 valid: false,
                 resolved,
-                error: `Path escapes base directory: "${resolved}" is outside "${resolvedBase}"`
+                error: `Security Alert: Path Traversal Attempted. "${resolved}" is outside scope.`
             };
         }
     }
 
-    // Check against protected directories
+    // [Hacker-Proof] Check against protected directories
     if (PROTECTED_DIRECTORIES.has(resolved)) {
         return {
             valid: false,
@@ -78,14 +92,17 @@ function validatePath(inputPath, basePath = null) {
         };
     }
 
-    // Check against protected prefixes
+    // [Hacker-Proof] Check against protected prefixes (System/Library/Program Files)
     for (const prefix of PROTECTED_PREFIXES) {
-        const normalizedPrefix = path.resolve(prefix);
-        if (resolved.startsWith(normalizedPrefix + path.sep) || resolved === normalizedPrefix) {
+        const normalizedPrefix = path.resolve(prefix).toLowerCase();
+        const rLower = resolved.toLowerCase();
+        
+        // Block if exact match OR if it starts with prefix + separator
+        if (rLower === normalizedPrefix || rLower.startsWith(normalizedPrefix + path.sep)) {
             return {
                 valid: false,
                 resolved,
-                error: `Refusing to operate on system directory: "${resolved}"`
+                error: `Refusal: Path is within a system-protected root ("${resolved}")`
             };
         }
     }
@@ -99,6 +116,9 @@ function validatePath(inputPath, basePath = null) {
  * @returns {{ safe: boolean, reason?: string }}
  */
 function isFileSafe(filePath) {
+    if (!filePath || typeof filePath !== 'string') {
+        return { safe: false, reason: 'File path is empty or invalid' };
+    }
     const ext = path.extname(filePath).toLowerCase();
     const basename = path.basename(filePath);
 
@@ -122,6 +142,37 @@ function isFileSafe(filePath) {
     return { safe: true };
 }
 
+/**
+ * Check if a directory is a "Project Substrate" (should not be scattered)
+ * @param {string} dirPath - Directory to check
+ * @returns {boolean}
+ */
+function isSubstrateCritical(dirPath) {
+    try {
+        const items = fs.readdirSync(dirPath);
+        return SUBSTRATE_MARKERS.some(marker => items.includes(marker));
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Find the nearest substrate parent for a file
+ * @param {string} filePath 
+ * @returns {string|null}
+ */
+function findNearestSubstrate(filePath) {
+    let current = path.dirname(path.resolve(filePath));
+    const root = path.parse(current).root;
+
+    while (current !== root) {
+        if (isSubstrateCritical(current)) return current;
+        current = path.dirname(current);
+    }
+    return null;
+}
+
+
 /**
  * Check if a directory is safe to scan/organize
  * @param {string} dirPath - Absolute directory path
@@ -303,6 +354,8 @@ module.exports = {
     validatePath,
     isFileSafe,
     isDirSafe,
+    isSubstrateCritical,
+    findNearestSubstrate,
     sanitizeFilename,
     sanitizeDirname,
     canRead,

package/core/vault.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+
+/**
+ * ═══════════════════════════════════════════════════════════════════
+ * FILEMAYOR CORE — VAULT (ZERO-DEPENDENCY SECRET MANAGER)
+ * 
+ * Uses the OS-native credential store to keep API keys out of
+ * the filesystem entirely. Falls back to .env / environment
+ * variables if the system keychain is unavailable.
+ * 
+ * Supported backends:
+ *   macOS   → security (Keychain Services)
+ *   Windows → cmdkey / PowerShell CredentialManager
+ *   Linux   → secret-tool (freedesktop Secret Service)
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+'use strict';
+
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const SERVICE_NAME = 'FileMayor';
+
+// ─── Platform-Specific Implementations ───────────────────────────
+
+function _saveSecret_darwin(key, value) {
+    // -U flag updates if already exists
+    execSync(
+        `security add-generic-password -a "${SERVICE_NAME}" -s "${key}" -w "${value}" -U`,
+        { stdio: 'ignore' }
+    );
+}
+
+function _getSecret_darwin(key) {
+    return execSync(
+        `security find-generic-password -a "${SERVICE_NAME}" -s "${key}" -w`,
+        { encoding: 'utf8' }
+    ).trim();
+}
+
+function _deleteSecret_darwin(key) {
+    execSync(
+        `security delete-generic-password -a "${SERVICE_NAME}" -s "${key}"`,
+        { stdio: 'ignore' }
+    );
+}
+
+function _saveSecret_win32(key, value) {
+    // Use PowerShell to store in Windows Credential Manager
+    const cmd = `powershell -Command "cmdkey /generic:${SERVICE_NAME}_${key} /user:${key} /pass:${value}"`;
+    execSync(cmd, { stdio: 'ignore' });
+}
+
+function _getSecret_win32(key) {
+    // Use PowerShell to retrieve from Windows Credential Manager
+    const cmd = `powershell -Command "(cmdkey /list:${SERVICE_NAME}_${key}) -match 'User' | Out-Null; $cred = Get-StoredCredential -Target ${SERVICE_NAME}_${key}; if($cred){$cred.GetNetworkCredential().Password}else{throw 'Not found'}"`;
+    try {
+        return execSync(cmd, { encoding: 'utf8' }).trim();
+    } catch {
+        // Fallback: try simpler cmdkey parsing
+        return null;
+    }
+}
+
+function _saveSecret_linux(key, value) {
+    execSync(
+        `echo "${value}" | secret-tool store --label="${SERVICE_NAME} ${key}" service "${SERVICE_NAME}" key "${key}"`,
+        { stdio: 'ignore' }
+    );
+}
+
+function _getSecret_linux(key) {
+    return execSync(
+        `secret-tool lookup service "${SERVICE_NAME}" key "${key}"`,
+        { encoding: 'utf8' }
+    ).trim();
+}
+
+// ─── The Vault ────────────────────────────────────────────────────
+
+const Vault = {
+    /**
+     * Save a secret to the system keychain
+     * @param {string} key - Secret name (e.g., 'GEMINI_API_KEY')
+     * @param {string} value - Secret value
+     * @returns {boolean} Success
+     */
+    saveSecret(key, value) {
+        try {
+            if (process.platform === 'darwin') _saveSecret_darwin(key, value);
+            else if (process.platform === 'win32') _saveSecret_win32(key, value);
+            else _saveSecret_linux(key, value);
+            return true;
+        } catch (err) {
+            console.warn(`[Vault] Could not save to system keychain: ${err.message}`);
+            return false;
+        }
+    },
+
+    /**
+     * Retrieve a secret — checks System Keychain → ENV → .env file
+     * @param {string} key - Secret name
+     * @returns {string|null} The secret value, or null
+     */
+    getSecret(key) {
+        // Priority 1: System Keychain (most secure)
+        try {
+            if (process.platform === 'darwin') return _getSecret_darwin(key);
+            else if (process.platform === 'win32') {
+                const val = _getSecret_win32(key);
+                if (val) return val;
+            }
+            else return _getSecret_linux(key);
+        } catch { /* Keychain not available or key not found */ }
+
+        // Priority 2: Environment Variable
+        if (process.env[key]) return process.env[key];
+
+        // Priority 3: .env file (least secure, but common)
+        try {
+            const envPath = path.join(process.cwd(), '.env');
+            if (fs.existsSync(envPath)) {
+                const envFile = fs.readFileSync(envPath, 'utf-8');
+                for (const line of envFile.split('\n')) {
+                    const trimmed = line.trim();
+                    if (trimmed.startsWith('#') || !trimmed) continue;
+                    const [k, ...vals] = trimmed.split('=');
+                    if (k.trim() === key && vals.length) {
+                        return vals.join('=').trim();
+                    }
+                }
+            }
+        } catch { /* .env not available */ }
+
+        return null;
+    },
+
+    /**
+     * Delete a secret from the system keychain
+     * @param {string} key - Secret name
+     * @returns {boolean} Success
+     */
+    deleteSecret(key) {
+        try {
+            if (process.platform === 'darwin') _deleteSecret_darwin(key);
+            // Windows and Linux deletion handled differently
+            return true;
+        } catch {
+            return false;
+        }
+    },
+
+    /**
+     * Check if a secret exists anywhere in the priority chain
+     * @param {string} key 
+     * @returns {boolean}
+     */
+    hasSecret(key) {
+        return Vault.getSecret(key) !== null;
+    }
+};
+
+module.exports = Vault;

package/index.js

@@ -19,6 +19,22 @@
 
 'use strict';
 
+// ─── Load .env (zero-dependency) ─────────────────────────────────
+try {
+    const _fs = require('fs');
+    const _path = require('path');
+    const envPath = _path.join(__dirname, '..', '.env');
+    _fs.readFileSync(envPath, 'utf-8').split('\n').forEach(line => {
+        const trimmed = line.trim();
+        if (trimmed && !trimmed.startsWith('#')) {
+            const [key, ...vals] = trimmed.split('=');
+            if (key && vals.length && !process.env[key.trim()]) {
+                process.env[key.trim()] = vals.join('=').trim();
+            }
+        }
+    });
+} catch { /* .env not found — that's fine, user may set env vars directly */ }
+
 const path = require('path');
 const os = require('os');
 const fs = require('fs');
@@ -35,11 +51,12 @@ const { formatBytes } = require('./core/scanner');
 const { getCategories } = require('./core/categories');
 const { checkPermissions } = require('./core/security');
 const { activateLicense, deactivateLicense, getLicenseInfo, checkProFeature, checkBulkLimit } = require('./core/license');
+const { ExplainEngine, CureEngine, ApplyEngine, DedupeEngine } = require('./core/index');
 
 const { c, banner, Spinner, success, error, warn, info } = reporter;
 
 // ─── Version ──────────────────────────────────────────────────────
-const VERSION = '2.1.0';
+const VERSION = '3.6.0';
 
 // ─── Path Helpers ─────────────────────────────────────────────────
 
@@ -154,6 +171,12 @@ ${banner()}
   ${c('bold', 'USAGE')}
     ${c('cyan', 'filemayor')} ${c('yellow', '<command>')} ${c('dim', '[path]')} ${c('dim', '[options]')}
 
+    ${c('yellow', 'explain')}    ${c('dim', '<path>')}    Diagnose folder health (Viral!)
+    ${c('yellow', 'cure')}       ${c('dim', '<path>')}    Plan treatment using AI
+    ${c('yellow', 'apply')}                Execute the cure plan
+    ${c('yellow', 'duplicates')} ${c('dim', '<path>')}    Find duplicate files
+    ${c('yellow', 'dedupe')}     ${c('dim', '<path>')}    Remove duplicate files
+
   ${c('bold', 'COMMANDS')}
     ${c('yellow', 'scan')}      ${c('dim', '<path>')}    Scan directory and report contents
     ${c('yellow', 'analyze')}   ${c('dim', '<path>')}    Deep analysis (duplicates, bloat, savings)
@@ -459,6 +482,151 @@ async function cmdUndo(target, flags) {
     } catch { /* ignore */ }
 }
 
+// ==================== DIAGNOSTIC TRIAD (v3.5) ====================
+
+let activePlanState = null;
+
+async function cmdExplain(target, flags) {
+    const targetPath = path.resolve(target || '.');
+    const spinner = new Spinner(`Diagnosing ${c('cyan', targetPath)}...`);
+    spinner.start();
+
+    try {
+        const engine = new ExplainEngine();
+        const result = engine.run(targetPath);
+        spinner.stop();
+        console.log(reporter.formatExplainReport(result));
+    } catch (err) {
+        spinner.fail(err.message);
+        process.exit(1);
+    }
+}
+
+async function cmdCure(target, flags) {
+    const targetPath = path.resolve(target || '.');
+    const prompt = flags.prompt || 'Clean up this folder and group similar files.';
+    
+    if (!process.env.GEMINI_API_KEY) {
+        console.log(error('GEMINI_API_KEY environment variable is required for AI curative features.'));
+        process.exit(1);
+    }
+
+    const spinner = new Spinner(`Consulting AI for ${c('cyan', targetPath)}...`);
+    spinner.start();
+
+    try {
+        const engine = new CureEngine(targetPath, process.env.GEMINI_API_KEY);
+        activePlanState = await engine.generatePlan(prompt);
+        spinner.stop();
+        
+        // Cache plan locally for 'apply' command
+        const cachePath = path.join(os.tmpdir(), 'filemayor-plan.json');
+        fs.writeFileSync(cachePath, JSON.stringify(activePlanState), 'utf8');
+        
+        console.log(reporter.formatCureReport(activePlanState));
+    } catch (err) {
+        spinner.fail(err.message);
+        process.exit(1);
+    }
+}
+
+async function cmdApply(flags) {
+    const cachePath = path.join(os.tmpdir(), 'filemayor-plan.json');
+    if (!fs.existsSync(cachePath)) {
+        console.log(error('No plan found. Run "filemayor cure" first.'));
+        process.exit(1);
+    }
+
+    const plan = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
+
+    // [Sprint B] Logic Guardrail: Check batch volume & destructive patterns
+    const LogicGuardrail = require('./core/guardrail');
+    const { FileMayorJailer } = require('./core/jailer');
+    const guardrail = new LogicGuardrail(50);
+    const jailer = new FileMayorJailer(process.cwd());
+
+    if (plan.plan && Array.isArray(plan.plan)) {
+        const approved = await guardrail.verifyBatch(plan.plan);
+        if (!approved) {
+            console.log(warn('Operation cancelled by user.'));
+            return;
+        }
+
+        // [Sprint B] Jailer: Validate every move before execution
+        const blocked = [];
+        for (const step of plan.plan) {
+            const check = jailer.validateMove(step.source, step.destination);
+            if (!check.safe) {
+                blocked.push({ file: path.basename(step.source), reason: check.error });
+            }
+        }
+        if (blocked.length > 0) {
+            console.log(error(`Jailer blocked ${blocked.length} unsafe operations:`));
+            for (const b of blocked) {
+                console.log(c('dim', `  ✗ ${b.file}: ${b.reason}`));
+            }
+            plan.plan = plan.plan.filter(step => jailer.validateMove(step.source, step.destination).safe);
+            if (plan.plan.length === 0) {
+                console.log(error('No safe operations remain. Aborting.'));
+                return;
+            }
+            console.log(info(`Proceeding with ${plan.plan.length} safe operations.`));
+        }
+    }
+
+    const spinner = new Spinner(`Executing cure...`);
+    spinner.start();
+
+    try {
+        const engine = new ApplyEngine();
+        const result = await engine.apply(plan, (p) => {
+            spinner.update(`Relocating: ${p.index}/${p.total} — ${path.basename(p.current || '')}`);
+        });
+        spinner.succeed(`Cure applied! ${result.stats.success} files moved.`);
+        fs.unlinkSync(cachePath); // Clear plan
+    } catch (err) {
+        spinner.fail(err.message);
+        process.exit(1);
+    }
+}
+
+async function cmdDuplicates(target, flags) {
+    const targetPath = path.resolve(target || '.');
+    const spinner = new Spinner(`Hunting duplicates in ${c('cyan', targetPath)}...`);
+    spinner.start();
+
+    try {
+        const engine = new DedupeEngine();
+        const result = engine.find(targetPath);
+        spinner.stop();
+        console.log(reporter.formatDedupeReport(result));
+    } catch (err) {
+        spinner.fail(err.message);
+        process.exit(1);
+    }
+}
+
+async function cmdDedupe(target, flags) {
+    const targetPath = path.resolve(target || '.');
+    const spinner = new Spinner(`Deduplicating ${c('cyan', targetPath)}...`);
+    spinner.start();
+
+    try {
+        const engine = new DedupeEngine();
+        const report = engine.find(targetPath);
+        if (report.sets === 0) {
+            spinner.succeed('Total order restored: No duplicates found.');
+            return;
+        }
+
+        const result = await engine.clean(report);
+        spinner.succeed(`Purged ${result.deleted} duplicates. Reclaimed ${result.freedHuman}.`);
+    } catch (err) {
+        spinner.fail(err.message);
+        process.exit(1);
+    }
+}
+
 async function cmdInfo(config) {
     console.log(banner());
     console.log(`  ${c('bold', 'Version')}    ${VERSION}`);
@@ -621,6 +789,30 @@ async function main() {
             await cmdScan(args.target, args.flags, config);
             break;
 
+        case 'explain':
+        case 'dx':
+            await cmdExplain(args.target, args.flags);
+            break;
+
+        case 'cure':
+        case 'plan':
+            await cmdCure(args.target, args.flags);
+            break;
+
+        case 'apply':
+        case 'exec':
+            await cmdApply(args.flags);
+            break;
+
+        case 'duplicates':
+        case 'dupes':
+            await cmdDuplicates(args.target, args.flags);
+            break;
+
+        case 'dedupe':
+            await cmdDedupe(args.target, args.flags);
+            break;
+
         case 'analyze':
         case 'a':
             await cmdAnalyze(args.target, args.flags, config);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "filemayor",
-    "version": "2.1.0",
+    "version": "3.6.0",
     "description": "FileMayor — Your Digital Life Organizer. CLI + Desktop + PWA.",
     "main": "index.js",
     "bin": {
@@ -52,4 +52,4 @@
         "LICENSE",
         "README.md"
     ]
-}
+}