filemayor 2.0.0

package/core/organizer.js

@@ -0,0 +1,528 @@
+#!/usr/bin/env node
+
+/**
+ * ═══════════════════════════════════════════════════════════════════
+ * FILEMAYOR CORE — ORGANIZER
+ * Intelligent file organization with dry-run, rollback journal,
+ * naming conventions, duplicate detection, and batch operations.
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { categorize, getCategories } = require('./categories');
+const { scan } = require('./scanner');
+const { validatePath, isFileSafe, sanitizeFilename, canWrite, createSnapshot } = require('./security');
+const { formatBytes } = require('./scanner');
+
+// ─── Naming Conventions ───────────────────────────────────────────
+
+const NAMING_CONVENTIONS = {
+    /**
+     * Category prefix: BIZ_001_Document.pdf
+     */
+    category_prefix: (file, category, index) => {
+        const prefix = category.toUpperCase().slice(0, 4);
+        const padded = String(index + 1).padStart(3, '0');
+        const cleanName = cleanFilename(file.name);
+        return `${prefix}_${padded}_${cleanName}`;
+    },
+
+    /**
+     * Date prefix: 2024-01-15_Document.pdf
+     */
+    date_prefix: (file) => {
+        const date = new Date(file.modified);
+        const year = date.getFullYear();
+        const month = String(date.getMonth() + 1).padStart(2, '0');
+        const day = String(date.getDate()).padStart(2, '0');
+        const cleanName = cleanFilename(file.name);
+        return `${year}-${month}-${day}_${cleanName}`;
+    },
+
+    /**
+     * Clean title only: Document.pdf (just sanitize)
+     */
+    clean: (file) => {
+        return cleanFilename(file.name);
+    },
+
+    /**
+     * Keep original: no renaming
+     */
+    original: (file) => {
+        return file.name;
+    }
+};
+
+/**
+ * Clean a filename by removing junk patterns
+ * @param {string} filename - Original filename
+ * @returns {string} Cleaned filename
+ */
+function cleanFilename(filename) {
+    const ext = path.extname(filename);
+    let base = path.basename(filename, ext);
+
+    // Remove common junk patterns
+    base = base
+        .replace(/[\[\(]\s*\d+\s*[\]\)]/g, '')           // [1], (2)
+        .replace(/\s*-\s*Copy\s*(\(\d+\))?/gi, '')       // - Copy, - Copy (2)
+        .replace(/\s*\(\d+\)\s*$/g, '')                   // (1) at end
+        .replace(/^\d{10,}_/g, '')                         // Unix timestamp prefix
+        .replace(/^IMG_\d+/gi, 'Photo')                   // IMG_20240115
+        .replace(/^DSC_?\d+/gi, 'Photo')                  // DSC_0001
+        .replace(/^VID_?\d+/gi, 'Video')                  // VID_20240115
+        .replace(/^Screenshot[_ ]\d{4}[-_]\d{2}[-_]\d{2}/gi, 'Screenshot') // Screenshot timestamps
+        .replace(/_{2,}/g, '_')                            // Multiple underscores
+        .replace(/\s{2,}/g, ' ')                           // Multiple spaces
+        .replace(/^[_\s]+|[_\s]+$/g, '');                  // Trim
+
+    // Convert to Title Case if all lowercase or all uppercase
+    if (base === base.toLowerCase() || base === base.toUpperCase()) {
+        base = base.replace(/\b\w/g, c => c.toUpperCase());
+    }
+
+    return sanitizeFilename(`${base}${ext}`);
+}
+
+// ─── Duplicate Detection ──────────────────────────────────────────
+
+const DUPLICATE_STRATEGIES = {
+    skip: 'skip',       // Don't move if destination exists
+    rename: 'rename',   // Add (1), (2), etc.
+    overwrite: 'overwrite', // Replace existing
+    newest: 'newest',   // Keep the newest file
+};
+
+/**
+ * Resolve a destination path with duplicate handling
+ * @param {string} destPath - Target destination path
+ * @param {string} strategy - Duplicate resolution strategy
+ * @returns {{ path: string, action: string }}
+ */
+function resolveDuplicate(destPath, strategy = 'rename') {
+    if (!fs.existsSync(destPath)) {
+        return { path: destPath, action: 'move' };
+    }
+
+    switch (strategy) {
+        case 'skip':
+            return { path: destPath, action: 'skip' };
+
+        case 'overwrite':
+            return { path: destPath, action: 'overwrite' };
+
+        case 'rename':
+        default: {
+            const dir = path.dirname(destPath);
+            const ext = path.extname(destPath);
+            const base = path.basename(destPath, ext);
+            let counter = 1;
+            let newPath;
+
+            do {
+                newPath = path.join(dir, `${base} (${counter})${ext}`);
+                counter++;
+            } while (fs.existsSync(newPath) && counter < 1000);
+
+            return { path: newPath, action: 'rename' };
+        }
+    }
+}
+
+// ─── Move Plan ────────────────────────────────────────────────────
+
+/**
+ * @typedef {Object} MovePlanItem
+ * @property {string} source - Source file path
+ * @property {string} destination - Target destination path
+ * @property {string} category - File category
+ * @property {string} originalName - Original filename
+ * @property {string} newName - New filename (after convention applied)
+ * @property {number} size - File size in bytes
+ * @property {string} action - Action to take: move, skip, rename, overwrite
+ */
+
+/**
+ * Generate a move plan without executing (dry-run)
+ * @param {string} srcDir - Source directory to organize
+ * @param {Object} options - Organization options
+ * @returns {{ plan: MovePlanItem[], summary: Object }}
+ */
+function generatePlan(srcDir, options = {}) {
+    const {
+        naming = 'original',
+        outputDir = null,          // null = organize in-place (subdirs)
+        flat = false,              // Flat structure vs nested
+        duplicateStrategy = 'rename',
+        customCategories = null,
+        scanOptions = {},
+    } = options;
+
+    // Scan the directory
+    const scanResult = scan(srcDir, {
+        ...scanOptions,
+        includeDirectories: false
+    });
+
+    const categories = getCategories(customCategories);
+    const plan = [];
+    const categoryCounts = {};
+    const namingFn = NAMING_CONVENTIONS[naming] || NAMING_CONVENTIONS.original;
+
+    // Build the plan
+    for (const file of scanResult.files) {
+        const category = file.category;
+        categoryCounts[category] = (categoryCounts[category] || 0);
+
+        // Determine new filename
+        const newName = namingFn(file, category, categoryCounts[category]);
+        categoryCounts[category]++;
+
+        // Determine destination directory
+        const catDef = categories[category];
+        const catLabel = catDef ? catDef.label : 'Other';
+        const destDir = outputDir
+            ? path.join(outputDir, catLabel)
+            : path.join(srcDir, catLabel);
+        const destPath = path.join(destDir, newName);
+
+        // Skip if source and destination are the same
+        if (path.resolve(file.path) === path.resolve(destPath)) {
+            continue;
+        }
+
+        // Handle duplicates
+        const resolved = resolveDuplicate(destPath, duplicateStrategy);
+
+        plan.push({
+            source: file.path,
+            destination: resolved.path,
+            category,
+            categoryLabel: catLabel,
+            originalName: file.name,
+            newName: path.basename(resolved.path),
+            size: file.size,
+            sizeHuman: file.sizeHuman,
+            action: resolved.action,
+            ext: file.ext
+        });
+    }
+
+    // Build summary
+    const summary = {
+        totalFiles: plan.length,
+        totalSize: plan.reduce((sum, p) => sum + p.size, 0),
+        totalSizeHuman: formatBytes(plan.reduce((sum, p) => sum + p.size, 0)),
+        categories: {},
+        actions: { move: 0, skip: 0, rename: 0, overwrite: 0 },
+        scanStats: scanResult.stats
+    };
+
+    for (const item of plan) {
+        summary.actions[item.action]++;
+        if (!summary.categories[item.categoryLabel]) {
+            summary.categories[item.categoryLabel] = { count: 0, size: 0 };
+        }
+        summary.categories[item.categoryLabel].count++;
+        summary.categories[item.categoryLabel].size += item.size;
+    }
+
+    // Add human-readable size to each category
+    for (const cat of Object.values(summary.categories)) {
+        cat.sizeHuman = formatBytes(cat.size);
+    }
+
+    return { plan, summary };
+}
+
+// ─── Execution ────────────────────────────────────────────────────
+
+/**
+ * Execute a move plan with journal logging for rollback
+ * @param {MovePlanItem[]} plan - The move plan to execute
+ * @param {Object} options - Execution options
+ * @returns {{ results: Object[], journal: Object[], summary: Object }}
+ */
+function executePlan(plan, options = {}) {
+    const {
+        onProgress = null,
+        onError = null,
+        journalPath = null,   // Path to save rollback journal
+        abortOnError = false, // Stop on first error
+    } = options;
+
+    const results = [];
+    const journal = [];
+    let succeeded = 0;
+    let failed = 0;
+    let skipped = 0;
+
+    for (let i = 0; i < plan.length; i++) {
+        const item = plan[i];
+
+        // Progress callback
+        if (onProgress) {
+            onProgress({
+                current: i + 1,
+                total: plan.length,
+                percent: Math.round(((i + 1) / plan.length) * 100),
+                file: item.originalName,
+                action: item.action,
+                category: item.categoryLabel
+            });
+        }
+
+        // Skip items marked as skip
+        if (item.action === 'skip') {
+            results.push({ ...item, status: 'skipped', error: null });
+            skipped++;
+            continue;
+        }
+
+        // Safety check
+        const safeCheck = isFileSafe(item.source);
+        if (!safeCheck.safe) {
+            const error = `Safety check failed: ${safeCheck.reason}`;
+            results.push({ ...item, status: 'error', error });
+            failed++;
+            if (onError) onError({ item, error });
+            if (abortOnError) break;
+            continue;
+        }
+
+        // Create destination directory
+        const destDir = path.dirname(item.destination);
+        try {
+            fs.mkdirSync(destDir, { recursive: true });
+        } catch (err) {
+            const error = `Failed to create directory: ${err.message}`;
+            results.push({ ...item, status: 'error', error });
+            failed++;
+            if (onError) onError({ item, error });
+            if (abortOnError) break;
+            continue;
+        }
+
+        // Create pre-move snapshot for integrity
+        const snapshot = createSnapshot(item.source);
+
+        // Execute the move
+        try {
+            // Handle overwrite
+            if (item.action === 'overwrite' && fs.existsSync(item.destination)) {
+                fs.unlinkSync(item.destination);
+            }
+
+            // Perform the move
+            fs.renameSync(item.source, item.destination);
+
+            // Journal entry for rollback
+            const journalEntry = {
+                source: item.source,
+                destination: item.destination,
+                originalName: item.originalName,
+                newName: item.newName,
+                size: item.size,
+                timestamp: Date.now(),
+                snapshot
+            };
+            journal.push(journalEntry);
+
+            results.push({ ...item, status: 'success', error: null });
+            succeeded++;
+        } catch (err) {
+            // If rename fails (cross-device), try copy + delete
+            try {
+                fs.copyFileSync(item.source, item.destination);
+                fs.unlinkSync(item.source);
+
+                const journalEntry = {
+                    source: item.source,
+                    destination: item.destination,
+                    originalName: item.originalName,
+                    newName: item.newName,
+                    size: item.size,
+                    timestamp: Date.now(),
+                    snapshot,
+                    crossDevice: true
+                };
+                journal.push(journalEntry);
+
+                results.push({ ...item, status: 'success', error: null });
+                succeeded++;
+            } catch (copyErr) {
+                const error = `Move failed: ${copyErr.message}`;
+                results.push({ ...item, status: 'error', error });
+                failed++;
+                if (onError) onError({ item, error });
+                if (abortOnError) break;
+            }
+        }
+    }
+
+    // Save journal to disk if path provided
+    if (journalPath && journal.length > 0) {
+        try {
+            const existing = fs.existsSync(journalPath)
+                ? JSON.parse(fs.readFileSync(journalPath, 'utf8'))
+                : [];
+            const merged = [...existing, ...journal];
+            fs.writeFileSync(journalPath, JSON.stringify(merged, null, 2), 'utf8');
+        } catch (err) {
+            // Journal save failed — non-fatal
+        }
+    }
+
+    const summary = {
+        total: plan.length,
+        succeeded,
+        failed,
+        skipped,
+        totalSize: plan.reduce((sum, p) => sum + p.size, 0),
+        totalSizeHuman: formatBytes(plan.reduce((sum, p) => sum + p.size, 0))
+    };
+
+    return { results, journal, summary };
+}
+
+// ─── Rollback (Undo) ──────────────────────────────────────────────
+
+/**
+ * Rollback operations using a journal
+ * @param {Object[]} journal - Journal entries from executePlan
+ * @param {Object} options - Rollback options
+ * @returns {{ undone: number, failed: number, errors: string[] }}
+ */
+function rollback(journal, options = {}) {
+    const { onProgress = null } = options;
+    let undone = 0;
+    let failed = 0;
+    const errors = [];
+
+    // Process in reverse order (most recent first)
+    const reversed = [...journal].reverse();
+
+    for (let i = 0; i < reversed.length; i++) {
+        const entry = reversed[i];
+
+        if (onProgress) {
+            onProgress({
+                current: i + 1,
+                total: reversed.length,
+                percent: Math.round(((i + 1) / reversed.length) * 100),
+                file: entry.originalName
+            });
+        }
+
+        try {
+            // Ensure source directory exists
+            const sourceDir = path.dirname(entry.source);
+            fs.mkdirSync(sourceDir, { recursive: true });
+
+            // Move back
+            if (entry.crossDevice) {
+                fs.copyFileSync(entry.destination, entry.source);
+                fs.unlinkSync(entry.destination);
+            } else {
+                fs.renameSync(entry.destination, entry.source);
+            }
+
+            undone++;
+        } catch (err) {
+            failed++;
+            errors.push(`Failed to undo ${entry.originalName}: ${err.message}`);
+        }
+    }
+
+    return { undone, failed, errors };
+}
+
+/**
+ * Load a journal from disk
+ * @param {string} journalPath - Path to journal file
+ * @returns {Object[]} Journal entries
+ */
+function loadJournal(journalPath) {
+    try {
+        if (!fs.existsSync(journalPath)) return [];
+        return JSON.parse(fs.readFileSync(journalPath, 'utf8'));
+    } catch {
+        return [];
+    }
+}
+
+// ─── Convenience Functions ────────────────────────────────────────
+
+/**
+ * Organize a directory (scan, plan, execute) in one call
+ * @param {string} dirPath - Directory to organize
+ * @param {Object} options - Full options
+ * @returns {{ results: Object[], journal: Object[], planSummary: Object, execSummary: Object }}
+ */
+function organize(dirPath, options = {}) {
+    const {
+        dryRun = false,
+        naming = 'original',
+        outputDir = null,
+        duplicateStrategy = 'rename',
+        journalPath = null,
+        onProgress = null,
+        onError = null,
+        abortOnError = false,
+        scanOptions = {},
+        customCategories = null,
+    } = options;
+
+    // Generate plan
+    const { plan, summary: planSummary } = generatePlan(dirPath, {
+        naming,
+        outputDir,
+        duplicateStrategy,
+        scanOptions,
+        customCategories,
+    });
+
+    if (dryRun) {
+        return {
+            dryRun: true,
+            plan,
+            planSummary,
+            results: [],
+            journal: [],
+            execSummary: null
+        };
+    }
+
+    // Execute
+    const { results, journal, summary: execSummary } = executePlan(plan, {
+        onProgress,
+        onError,
+        journalPath: journalPath || path.join(dirPath, '.filemayor-journal.json'),
+        abortOnError
+    });
+
+    return {
+        dryRun: false,
+        plan,
+        planSummary,
+        results,
+        journal,
+        execSummary
+    };
+}
+
+module.exports = {
+    NAMING_CONVENTIONS,
+    DUPLICATE_STRATEGIES,
+    cleanFilename,
+    resolveDuplicate,
+    generatePlan,
+    executePlan,
+    rollback,
+    loadJournal,
+    organize
+};