filemayor 4.0.7 → 4.0.9

package/core/index.js

@@ -27,6 +27,7 @@ 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 PARAEngine = require('./engine/para-engine');
 const MetadataStore = require('./metadata-store');
 const strategist = require('./ai/strategist');
 const sentry = require('./ai/sentry');
@@ -119,6 +120,7 @@ module.exports = {
     ApplyEngine,
     PreviewEngine,
     DedupeEngine,
+    PARAEngine,
     MetadataStore,
 
     // Hardened Runtime

package/core/watcher.js

@@ -80,8 +80,15 @@ class FileWatcher extends EventEmitter {
             maxLogEntries: options.maxLogEntries || 10000,
             autoOrganize: options.autoOrganize || false,
             organizeOptions: options.organizeOptions || {},
+            // PARA mode (v4.0.9): route each new file into Projects/Areas/
+            // Resources/Archives by actionability as it lands. Journaled.
+            paraMode: options.paraMode || false,
+            paraConfig: options.paraConfig || {},
         };
 
+        this._fmfs = null;       // lazy — shared journal session for this watcher
+        this._paraEngine = null; // lazy — built on first PARA routing
+
         this._watchers = new Map();
         this._debounceTimers = new Map();
         this._running = false;
@@ -338,6 +345,11 @@ class FileWatcher extends EventEmitter {
             break; // First match wins
         }
 
+        // PARA mode — route the new file into its actionability bucket
+        if (this.options.paraMode && eventType === 'rename') {
+            this._routePara(fullPath, filename, watchDir, stats);
+        }
+
         // Auto-organize if enabled
         if (this.options.autoOrganize && eventType === 'rename') {
             // A new file appeared — organize the directory
@@ -353,6 +365,65 @@ class FileWatcher extends EventEmitter {
         }
     }
 
+    /** Lazy shared FileMayorFS — one journal session per watcher run. */
+    _getFmfs() {
+        if (!this._fmfs) {
+            const FileMayorFS = require('./fs-abstraction');
+            this._fmfs = new FileMayorFS();
+        }
+        return this._fmfs;
+    }
+
+    /**
+     * PARA mode: classify one new file by actionability and move it into
+     * Projects/Areas/Resources/Archives. Skips files already inside a
+     * bucket (no loops — the move itself fires another watch event).
+     */
+    _routePara(fullPath, filename, watchDir, stats) {
+        try {
+            if (!this._paraEngine) {
+                const PARAEngine = require('./engine/para-engine');
+                this._paraEngine = new PARAEngine(this.options.paraConfig);
+            }
+            const engine = this._paraEngine;
+            const folders = engine.config.folders;
+
+            const rel = path.relative(watchDir, fullPath);
+            const firstSegment = rel.split(path.sep)[0].toLowerCase();
+            const bucketNames = new Set(Object.values(folders).map(f => f.toLowerCase()));
+            if (bucketNames.has(firstSegment)) return; // already sorted
+
+            const fileInfo = {
+                name: filename,
+                path: fullPath,
+                category: categorize(path.extname(filename).toLowerCase()),
+                size: stats.size,
+                modified: stats.mtime,
+            };
+            const { bucket, reason } = engine._classify(fileInfo, rel, Date.now());
+            const destination = path.join(watchDir, folders[bucket], filename);
+
+            this._getFmfs().move(fullPath, destination)
+                .then(() => {
+                    this._stats.filesActioned++;
+                    this.emit('action', {
+                        action: 'para-route',
+                        source: fullPath,
+                        destination,
+                        bucket,
+                        reason,
+                    });
+                })
+                .catch((err) => {
+                    this._stats.errors++;
+                    this.emit('error', { action: 'para-route', path: fullPath, error: err.message });
+                });
+        } catch (err) {
+            this._stats.errors++;
+            this.emit('error', { action: 'para-route', path: fullPath, error: err.message });
+        }
+    }
+
     /**
      * Execute a matched rule
      */
@@ -400,13 +471,20 @@ class FileWatcher extends EventEmitter {
                     break;
 
                 case 'delete':
-                    fs.unlinkSync(event.path);
-                    this._stats.filesActioned++;
-                    this.emit('action', {
-                        action: 'delete',
-                        source: event.path,
-                        rule
-                    });
+                    // Trash-based (v4.0.9): journaled and reversible with undo.
+                    this._getFmfs().delete(event.path)
+                        .then(() => {
+                            this._stats.filesActioned++;
+                            this.emit('action', {
+                                action: 'delete',
+                                source: event.path,
+                                rule
+                            });
+                        })
+                        .catch((err) => {
+                            this._stats.errors++;
+                            this.emit('error', { action: 'delete', path: event.path, error: err.message, rule });
+                        });
                     break;
 
                 case 'log':

package/index.js

@@ -51,13 +51,14 @@ 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 { ExplainEngine, CureEngine, ApplyEngine, DedupeEngine, PARAEngine } = require('./core/index');
 const { ping: telemetryPing } = require('./core/telemetry');
 
 const { c, banner, Spinner, success, error, warn, info } = reporter;
 
 // ─── Version ──────────────────────────────────────────────────────
-const VERSION = '4.0.5';
+// Derived from package.json so it can never drift out of sync.
+const VERSION = require('./package.json').version;
 
 // ─── Path Helpers ─────────────────────────────────────────────────
 
@@ -117,6 +118,10 @@ function parseArgs(argv) {
             args.flags.depth = parseInt(raw[++i], 10);
         } else if (arg === '--naming' && raw[i + 1]) {
             args.flags.naming = raw[++i];
+        } else if (arg === '--archive-after' && raw[i + 1]) {
+            args.flags.archiveAfter = parseInt(raw[++i], 10);
+        } else if (arg === '--para') {
+            args.flags.para = true;
         } else if (arg === '--output' && raw[i + 1]) {
             args.flags.outputDir = raw[++i];
         } else if (arg === '--config' && raw[i + 1]) {
@@ -173,19 +178,20 @@ ${banner()}
     ${c('cyan', 'filemayor')} ${c('yellow', '<command>')} ${c('dim', '[path]')} ${c('dim', '[options]')}
 
     ${c('yellow', 'explain')}    ${c('dim', '<path>')}    Diagnose folder health
-    ${c('yellow', 'cure')}       ${c('dim', '<path>')}    Plan treatment using AI
+    ${c('yellow', 'cure')}       ${c('dim', '<path>')}    Plan treatment using AI (--para for PARA buckets)
     ${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('yellow', 'duplicates')} ${c('dim', '<path>')}    Find duplicates (content-hash)
+    ${c('yellow', 'dedupe')}     ${c('dim', '<path>')}    Trash duplicates (reversible with undo)
 
   ${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)
     ${c('yellow', 'organize')}  ${c('dim', '<path>')}    Organize files into categories
+    ${c('yellow', 'para')}      ${c('dim', '<path>')}    Sort by actionability — PARA method (then apply)
     ${c('yellow', 'clean')}     ${c('dim', '<path>')}    Find and remove junk files
-    ${c('yellow', 'watch')}     ${c('dim', '<path>')}    Watch directory for changes
-    ${c('yellow', 'init')}                Create .filemayor.yml config
-    ${c('yellow', 'undo')}      ${c('dim', '<path>')}    Undo last organization
+    ${c('yellow', 'watch')}     ${c('dim', '<path>')}    Watch directory (--para: auto-route new files)
+    ${c('yellow', 'init')}     ${c('dim', '[--para]')}   Create .filemayor.yml (--para scaffolds PARA folders)
+    ${c('yellow', 'undo')}                Undo last session (--list · --session <id> · --all)
     ${c('yellow', 'info')}                System info and version
     ${c('yellow', 'license')}  ${c('dim', '<action>')}  Manage license (activate|status|deactivate)
 
@@ -201,6 +207,8 @@ ${banner()}
     ${c('dim', '--config <path>')}     Custom config file
     ${c('dim', '--depth <n>')}         Max recursion depth
     ${c('dim', '--naming <type>')}     Naming: original|category_prefix|date_prefix|clean
+    ${c('dim', '--archive-after <n>')} PARA: months of inactivity before a file → Archives
+    ${c('dim', '--para')}              init: scaffold PARA folders + preset config
     ${c('dim', '--duplicates <s>')}    Duplicates: rename|skip|overwrite
     ${c('dim', '--extensions <e>')}    Filter by extensions (comma-separated)
     ${c('dim', '--output <path>')}     Output directory for organized files
@@ -214,6 +222,8 @@ ${banner()}
     ${c('dim', '$')} filemayor scan ~/Downloads
     ${c('dim', '$')} filemayor organize ~/Downloads --dry-run
     ${c('dim', '$')} filemayor organize ~/Downloads --naming category_prefix
+    ${c('dim', '$')} filemayor init --para ~/Documents
+    ${c('dim', '$')} filemayor para ~/Documents --archive-after 18
     ${c('dim', '$')} filemayor clean /var/tmp --yes
     ${c('dim', '$')} filemayor scan . --json | jq '.files | length'
     ${c('dim', '$')} filemayor watch ~/Downloads
@@ -372,7 +382,7 @@ async function cmdClean(target, flags, config) {
     if (format === 'table' && !flags.quiet) spinner.start();
 
     try {
-        const result = clean(targetPath, {
+        const result = await clean(targetPath, {
             dryRun,
             categories: flags.category || config.clean.categories,
             maxDepth: flags.depth || config.clean.maxDepth,
@@ -414,8 +424,14 @@ async function cmdWatch(target, flags, config) {
             naming: config.organize.naming,
             duplicateStrategy: config.organize.duplicates,
         },
+        paraMode: !!flags.para,
+        paraConfig: config.para || {},
     });
 
+    if (flags.para) {
+        console.log(info('PARA mode: new files route to Projects / Areas / Resources / Archives (journaled — undo works).'));
+    }
+
     watcher.on('watching', (data) => {
         console.log(success(`Watching: ${data.directory}`));
     });
@@ -454,6 +470,23 @@ async function cmdWatch(target, flags, config) {
 
 async function cmdInit(flags) {
     try {
+        if (flags.para) {
+            // PARA preset: write a tuned config AND scaffold the four folders
+            // with teaching READMEs so a first-timer understands the method.
+            const configPath = createConfigFile(process.cwd(), '.filemayor.yml', 'para');
+            console.log(success(`Created ${c('cyan', configPath)}`));
+
+            const engine = new PARAEngine();
+            const { created, folders } = engine.scaffold(process.cwd());
+            console.log(success(`Scaffolded PARA folders: ${c('cyan', Object.values(folders).join(', '))}`));
+            if (created.length) {
+                console.log(c('dim', `  ${created.length} item(s) created (folders + READMEs)`));
+            }
+            console.log('');
+            console.log(c('dim', '  Next:  ') + c('cyan', 'filemayor para .') + c('dim', '   then  ') + c('cyan', 'filemayor apply'));
+            return;
+        }
+
         const configPath = createConfigFile(process.cwd());
         console.log(success(`Created ${c('cyan', configPath)}`));
         console.log(c('dim', '  Edit this file to customize FileMayor settings'));
@@ -463,24 +496,100 @@ async function cmdInit(flags) {
     }
 }
 
+// ─── PARA: sort by actionability (Projects/Areas/Resources/Archives) ──
+async function cmdPara(target, flags, config) {
+    const targetPath = path.resolve(target || '.');
+
+    // Per-run override for the archive threshold.
+    const paraConfig = { ...(config.para || {}) };
+    if (Number.isFinite(flags.archiveAfter)) {
+        paraConfig.archiveAfterMonths = flags.archiveAfter;
+    }
+
+    const spinner = new Spinner(`Sorting ${c('cyan', targetPath)} by actionability (PARA)...`);
+    if (!flags.quiet) spinner.start();
+
+    try {
+        const engine = new PARAEngine(paraConfig);
+        const result = engine.plan(targetPath);
+        spinner.stop();
+
+        if (flags.format === 'json') {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+
+        // Cache the plan so `filemayor apply` can execute it (same path as cure).
+        const cachePath = path.join(os.tmpdir(), 'filemayor-plan.json');
+        fs.writeFileSync(cachePath, JSON.stringify(result), 'utf8');
+
+        console.log(reporter.formatCureReport(result));
+
+        // PARA-specific breakdown — the bucket is the whole point.
+        const b = result.summary.buckets;
+        console.log(c('bold', '  Into PARA buckets:'));
+        console.log(`    ${c('cyan', 'Projects')}  ${b.projects}   ${c('cyan', 'Areas')} ${b.areas}   ${c('cyan', 'Resources')} ${b.resources}   ${c('cyan', 'Archives')} ${b.archives}`);
+        for (const wn of (result.warnings || [])) {
+            console.log(c('dim', `    ⚠ ${wn}`));
+        }
+
+        if (result.plan.length === 0) {
+            console.log(info('Nothing to reorganise — run with a messier folder, or it is already PARA-sorted.'));
+        } else {
+            console.log('');
+            console.log(c('dim', '  Review the plan above, then run ') + c('cyan', 'filemayor apply') + c('dim', ' to execute (reversible with ') + c('cyan', 'filemayor undo') + c('dim', ').'));
+        }
+    } catch (err) {
+        spinner.fail(err.message);
+        process.exit(1);
+    }
+}
+
 async function cmdUndo(target, flags) {
-    const { JOURNAL_PATH, rollback: fsRollback } = require('./core/fs-abstraction');
+    const { JOURNAL_PATH, rollback: fsRollback, listSessions } = require('./core/fs-abstraction');
 
     if (!fs.existsSync(JOURNAL_PATH)) {
         console.log(info('No operations to undo (journal is empty)'));
         return;
     }
 
-    const spinner = new Spinner('Undoing operations...');
+    // undo --list: show the undoable session history, newest first.
+    if (flags.list) {
+        const sessions = listSessions(JOURNAL_PATH);
+        if (sessions.length === 0) {
+            console.log(info('No undoable sessions — the journal has nothing left to reverse.'));
+            return;
+        }
+        console.log(c('bold', '\n  UNDO HISTORY') + c('dim', ` — ${sessions.length} session${sessions.length === 1 ? '' : 's'}\n`));
+        for (const s of sessions) {
+            const when = s.end.replace('T', ' ').slice(0, 19);
+            const parts = [];
+            if (s.moves) parts.push(`${s.moves} move${s.moves === 1 ? '' : 's'}`);
+            if (s.deletes) parts.push(`${s.deletes} delete${s.deletes === 1 ? '' : 's'}`);
+            console.log(`  ${c('cyan', s.sessionId.padEnd(10))} ${c('dim', when)}  ${parts.join(', ')}`);
+        }
+        console.log(c('dim', "\n  Reverse one:  filemayor undo --session <id>"));
+        console.log(c('dim', '  Reverse all:  filemayor undo --all\n'));
+        return;
+    }
+
+    const scope = flags.session
+        ? `session ${flags.session}`
+        : flags.all ? 'all sessions' : 'the most recent session';
+    const spinner = new Spinner(`Undoing ${scope}...`);
     spinner.start();
 
     try {
-        const result = await fsRollback(JOURNAL_PATH);
+        const result = await fsRollback(JOURNAL_PATH, {
+            all: !!flags.all,
+            sessionId: typeof flags.session === 'string' ? flags.session : undefined,
+        });
         spinner.stop();
         if (result.count === 0) {
             console.log(info('Nothing to undo — no completed operations found in the journal'));
         } else {
-            console.log(success(`Undone ${result.count} operation${result.count === 1 ? '' : 's'}`));
+            const which = result.sessionId && !flags.all ? c('dim', ` (session ${result.sessionId})`) : '';
+            console.log(success(`Undone ${result.count} operation${result.count === 1 ? '' : 's'}`) + which);
         }
     } catch (err) {
         spinner.fail(err.message);
@@ -510,18 +619,33 @@ async function cmdExplain(target, flags) {
 
 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 prompt = flags.prompt || (flags.para
+        ? 'Sort this folder by actionability using the PARA method (Projects, Areas, Resources, Archives).'
+        : 'Clean up this folder and group similar files.');
+
+    // Multi-provider (v4.0.9): first key present wins — Anthropic, Gemini,
+    // then OpenAI. With no key at all, the core planner falls back to the
+    // free FileMayor proxy, so there is nothing to hard-fail on here.
+    const providers = [
+        ['ANTHROPIC_API_KEY', 'anthropic'],
+        ['GEMINI_API_KEY', 'gemini'],
+        ['OPENAI_API_KEY', 'openai'],
+    ];
+    let apiKey = '';
+    for (const [envVar, provider] of providers) {
+        if (process.env[envVar]) {
+            process.env.FM_AI_PROVIDER = provider;
+            process.env.FM_AI_API_KEY = process.env[envVar];
+            apiKey = process.env[envVar];
+            break;
+        }
     }
 
     const spinner = new Spinner(`Consulting AI for ${c('cyan', targetPath)}...`);
     spinner.start();
 
     try {
-        const engine = new CureEngine(targetPath, process.env.GEMINI_API_KEY);
+        const engine = new CureEngine(targetPath, apiKey);
         activePlanState = await engine.generatePlan(prompt);
         spinner.stop();
         
@@ -603,7 +727,7 @@ async function cmdDuplicates(target, flags) {
 
     try {
         const engine = new DedupeEngine();
-        const result = engine.find(targetPath);
+        const result = await engine.find(targetPath);
         spinner.stop();
         console.log(reporter.formatDedupeReport(result));
     } catch (err) {
@@ -619,14 +743,15 @@ async function cmdDedupe(target, flags) {
 
     try {
         const engine = new DedupeEngine();
-        const report = engine.find(targetPath);
+        const report = await 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}.`);
+        spinner.succeed(`Trashed ${result.deleted} duplicates. Reclaimed ${result.freedHuman}.`);
+        console.log(c('dim', `  Recoverable: files moved to FileMayor trash — 'filemayor undo' restores them.`));
     } catch (err) {
         spinner.fail(err.message);
         process.exit(1);
@@ -837,6 +962,11 @@ async function main() {
             await cmdOrganize(args.target, args.flags, config);
             break;
 
+        case 'para':
+        case 'pm':
+            await cmdPara(args.target, args.flags, config);
+            break;
+
         case 'clean':
         case 'cl':
         case 'c':

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "filemayor",
-    "version": "4.0.7",
+    "version": "4.0.9",
     "description": "FileMayor — Your intelligent filesystem clerk. CLI + Desktop + PWA.",
     "main": "index.js",
     "bin": {