folder-tidy 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kirtan-kalathiya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# folder-tidy
+
+`folder-tidy` is a proper Node.js CLI project for cleaning messy folders safely.
+
+It now has:
+
+- a cleaner project structure
+- modular source files
+- multiple organize modes
+- manifest history
+- undo support
+
+## Project Structure
+
+```text
+folder-tidy/
+├─ index.js
+├─ package.json
+└─ src/
+   ├─ cli.js
+   ├─ commands/
+   ├─ core/
+   └─ utils/
+```
+
+## Features
+
+- `tidy` command for organizing files
+- `undo` command for restoring the last run or a specific manifest
+- organize by `type`, `name`, or `date`
+- dry-run preview mode
+- recursive scanning
+- exclusion patterns
+- hidden file support
+- JSON report export
+- automatic collision-safe renaming
+- manifest storage in `.folder-tidy/`
+
+## Installation
+
+```bash
+npm install -g folder-tidy
+```
+
+## Commands
+
+### Organize files
+
+```bash
+folder-tidy tidy
+folder-tidy tidy --target ./Downloads
+folder-tidy tidy --mode name --dry-run
+folder-tidy tidy --mode date --recursive
+folder-tidy tidy --report reports/latest.json
+```
+
+You can still use the short default style too:
+
+```bash
+folder-tidy --dry-run
+```
+
+### Undo the last run
+
+```bash
+folder-tidy undo
+folder-tidy undo --target ./Downloads
+folder-tidy undo --manifest .folder-tidy/manifest-123.json
+folder-tidy undo --dry-run
+```
+
+## CLI Options For `tidy`
+
+```text
+--target <path>          Organize a specific directory
+--mode <type|name|date>  Choose how files are grouped
+--dry-run                Preview changes without moving files
+--recursive              Scan subfolders recursively
+--exclude <patterns>     Exclude files or folders, comma-separated globs
+--include-hidden         Include hidden files
+--report <file>          Save a JSON report
+--no-manifest            Skip saving an undo manifest
+--verbose                Show detailed logs
+```
+
+## CLI Options For `undo`
+
+```text
+--target <path>          Target directory that contains .folder-tidy manifests
+--manifest <file>        Restore a specific manifest file
+--dry-run                Preview restore actions without moving files
+--verbose                Show detailed logs
+```
+
+## Testing Locally
+
+```bash
+node index.js --help
+node index.js tidy --dry-run
+node index.js undo --help
+```
+
+## Version
+
+Current release: `1.0.0`

package/index.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('./src/cli').run(process.argv.slice(2));

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "folder-tidy",
+  "version": "1.0.0",
+  "description": "A smarter CLI to organize messy folders by type, name, or date with undo support",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "folder-tidy": "./index.js"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "help": "node index.js --help",
+    "test:smoke": "node index.js --help && node index.js tidy --dry-run && node index.js undo --help",
+    "prepublishOnly": "npm run test:smoke"
+  },
+  "keywords": [
+    "folder-tidy",
+    "cli",
+    "file-organizer",
+    "downloads-cleaner",
+    "automation",
+    "filesystem",
+    "productivity",
+    "nodejs",
+    "undo",
+    "file-management"
+  ],
+  "author": "kirtan kalathiya",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kirtan-kalathiya/folder-tidy.git"
+  },
+  "homepage": "https://github.com/kirtan-kalathiya/folder-tidy#readme",
+  "bugs": {
+    "url": "https://github.com/kirtan-kalathiya/folder-tidy/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}

package/src/cli.js

@@ -0,0 +1,68 @@
+const { VERSION } = require('./constants');
+const { printTidyHelp, runTidy } = require('./commands/tidy');
+const { printUndoHelp, runUndo } = require('./commands/undo');
+
+function printGlobalHelp() {
+  console.log(`
+folder-tidy ${VERSION}
+
+Commands:
+  tidy      Organize files in a folder
+  undo      Restore the latest tidy run or a specific manifest
+
+Usage:
+  folder-tidy tidy --target <path>
+  folder-tidy undo --target <path>
+
+Quick use:
+  folder-tidy --dry-run
+  folder-tidy --mode name
+
+Global options:
+  --help, -h     Show help
+  --version      Show version
+`);
+}
+
+function run(argv) {
+  if (argv.includes('--version')) {
+    console.log(VERSION);
+    return;
+  }
+
+  if (argv.length === 0) {
+    runTidy([], VERSION);
+    return;
+  }
+
+  const [command, ...rest] = argv;
+
+  if (command === '--help' || command === '-h' || command === 'help') {
+    printGlobalHelp();
+    return;
+  }
+
+  if (command === 'tidy') {
+    runTidy(rest, VERSION);
+    return;
+  }
+
+  if (command === 'undo') {
+    runUndo(rest);
+    return;
+  }
+
+  // Backward-compatible shorthand: treat options as tidy args.
+  if (command.startsWith('-')) {
+    runTidy(argv, VERSION);
+    return;
+  }
+
+  console.error(`Unknown command "${command}".`);
+  printGlobalHelp();
+  process.exit(1);
+}
+
+module.exports = {
+  run,
+};

package/src/commands/tidy.js

@@ -0,0 +1,129 @@
+const fs = require('fs');
+const { normalizePath } = require('../utils/paths');
+const { tidyDirectory } = require('../core/organizer');
+
+function printTidyHelp(version) {
+  console.log(`
+folder-tidy ${version}
+
+Usage:
+  folder-tidy tidy
+  folder-tidy tidy --target <path>
+  folder-tidy tidy --mode <type|name|date>
+
+Options:
+  --target <path>          Organize a specific directory
+  --mode <mode>            Organize by file type, file name, or modified date
+  --dry-run                Preview changes without moving anything
+  --recursive              Scan subfolders recursively
+  --exclude <patterns>     Exclude files or folders, comma-separated globs
+  --include-hidden         Include hidden files
+  --report <file>          Save a JSON report of the run
+  --no-manifest            Skip saving an undo manifest
+  --verbose                Show detailed skip and scan logs
+  --help, -h               Show tidy help
+`);
+}
+
+function parseTidyOptions(argv, version) {
+  const options = {
+    targetDir: process.cwd(),
+    dryRun: false,
+    verbose: false,
+    recursive: false,
+    includeHidden: false,
+    noManifest: false,
+    mode: 'type',
+    excludePatterns: [],
+    reportPath: null,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    if (arg === '--help' || arg === '-h') {
+      printTidyHelp(version);
+      process.exit(0);
+    }
+
+    if (arg === '--target' && argv[i + 1]) {
+      options.targetDir = argv[i + 1];
+      i += 1;
+      continue;
+    }
+
+    if (arg === '--mode' && argv[i + 1]) {
+      options.mode = argv[i + 1].toLowerCase();
+      i += 1;
+      continue;
+    }
+
+    if (arg === '--exclude' && argv[i + 1]) {
+      options.excludePatterns = argv[i + 1]
+        .split(',')
+        .map((pattern) => pattern.trim())
+        .filter(Boolean);
+      i += 1;
+      continue;
+    }
+
+    if (arg === '--report' && argv[i + 1]) {
+      options.reportPath = argv[i + 1];
+      i += 1;
+      continue;
+    }
+
+    if (arg === '--dry-run') options.dryRun = true;
+    if (arg === '--verbose' || arg === '-v') options.verbose = true;
+    if (arg === '--recursive') options.recursive = true;
+    if (arg === '--include-hidden') options.includeHidden = true;
+    if (arg === '--no-manifest') options.noManifest = true;
+  }
+
+  if (!['type', 'name', 'date'].includes(options.mode)) {
+    console.error(`Invalid mode "${options.mode}". Use type, name, or date.`);
+    process.exit(1);
+  }
+
+  return options;
+}
+
+function runTidy(argv, version) {
+  const options = parseTidyOptions(argv, version);
+  const targetDir = normalizePath(options.targetDir);
+
+  if (!fs.existsSync(targetDir) || !fs.statSync(targetDir).isDirectory()) {
+    console.error(`Target directory not found: ${targetDir}`);
+    process.exit(1);
+  }
+
+  const result = tidyDirectory(targetDir, options);
+
+  console.log('');
+  console.log('Summary');
+  console.log(`scanned: ${result.stats.scanned}`);
+  console.log(`moved: ${result.stats.moved}`);
+  console.log(`skipped: ${result.stats.skipped}`);
+  console.log(`errors: ${result.stats.errors}`);
+
+  if (Object.keys(result.stats.categories).length > 0) {
+    console.log('');
+    for (const folder of Object.keys(result.stats.categories).sort()) {
+      console.log(`${folder}: ${result.stats.categories[folder]}`);
+    }
+  }
+
+  if (result.manifestPath) {
+    console.log('');
+    console.log(`manifest: ${result.manifestPath}`);
+  }
+
+  if (result.reportPath) {
+    console.log(`report: ${result.reportPath}`);
+  }
+}
+
+module.exports = {
+  printTidyHelp,
+  runTidy,
+};

package/src/commands/undo.js

@@ -0,0 +1,123 @@
+const fs = require('fs');
+const path = require('path');
+const { VERSION } = require('../constants');
+const { ensureDirectory, getSafeDestination } = require('../core/filesystem');
+const { getLatestManifest, readManifest } = require('../core/manifest');
+const { normalizePath } = require('../utils/paths');
+
+function printUndoHelp() {
+  console.log(`
+folder-tidy ${VERSION}
+
+Usage:
+  folder-tidy undo
+  folder-tidy undo --target <path>
+  folder-tidy undo --manifest <file>
+
+Options:
+  --target <path>      Target directory that contains .folder-tidy manifests
+  --manifest <file>    Restore a specific manifest file
+  --dry-run            Preview restore actions without moving anything
+  --verbose            Show detailed logs
+  --help, -h           Show undo help
+`);
+}
+
+function parseUndoOptions(argv) {
+  const options = {
+    targetDir: process.cwd(),
+    manifestPath: null,
+    dryRun: false,
+    verbose: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    if (arg === '--help' || arg === '-h') {
+      printUndoHelp();
+      process.exit(0);
+    }
+
+    if (arg === '--target' && argv[i + 1]) {
+      options.targetDir = argv[i + 1];
+      i += 1;
+      continue;
+    }
+
+    if (arg === '--manifest' && argv[i + 1]) {
+      options.manifestPath = argv[i + 1];
+      i += 1;
+      continue;
+    }
+
+    if (arg === '--dry-run') options.dryRun = true;
+    if (arg === '--verbose' || arg === '-v') options.verbose = true;
+  }
+
+  return options;
+}
+
+function runUndo(argv) {
+  const options = parseUndoOptions(argv);
+  const targetDir = normalizePath(options.targetDir);
+  const manifestPath = options.manifestPath
+    ? normalizePath(options.manifestPath)
+    : getLatestManifest(targetDir);
+
+  if (!manifestPath || !fs.existsSync(manifestPath)) {
+    console.error('No manifest found to undo.');
+    process.exit(1);
+  }
+
+  const manifest = readManifest(manifestPath);
+  const moves = Array.isArray(manifest.moves) ? [...manifest.moves].reverse() : [];
+
+  console.log(`folder-tidy ${VERSION}`);
+  console.log(`command: undo`);
+  console.log(`manifest: ${manifestPath}`);
+  console.log(`target: ${targetDir}${options.dryRun ? ' (dry run)' : ''}`);
+  console.log('');
+
+  let restored = 0;
+  let skipped = 0;
+  let errors = 0;
+
+  for (const move of moves) {
+    const currentPath = path.join(targetDir, move.to);
+    const restoreDir = path.dirname(path.join(targetDir, move.from));
+    const restorePath = getSafeDestination(restoreDir, path.basename(move.from));
+
+    if (!fs.existsSync(currentPath)) {
+      if (options.verbose) console.log(`skip missing: ${move.to}`);
+      skipped += 1;
+      continue;
+    }
+
+    try {
+      ensureDirectory(restoreDir, options.dryRun);
+
+      if (!options.dryRun) {
+        fs.renameSync(currentPath, restorePath);
+      }
+
+      console.log(`${options.dryRun ? 'plan' : 'restore'}: ${move.to} -> ${path.relative(targetDir, restorePath)}`);
+      restored += 1;
+    } catch (error) {
+      console.error(`failed: ${move.to}`);
+      if (options.verbose) console.error(error.message);
+      errors += 1;
+    }
+  }
+
+  console.log('');
+  console.log('Summary');
+  console.log(`restored: ${restored}`);
+  console.log(`skipped: ${skipped}`);
+  console.log(`errors: ${errors}`);
+}
+
+module.exports = {
+  printUndoHelp,
+  runUndo,
+};

package/src/constants.js

@@ -0,0 +1,35 @@
+const VERSION = '3.0.0';
+const APP_FOLDER = '.folder-tidy';
+const MANIFEST_PREFIX = 'manifest-';
+const INTERNAL_FILES = new Set(['index.js', 'package.json', 'README.md', 'LICENSE']);
+
+const CATEGORY_RULES = {
+  Images: ['.jpg', '.jpeg', '.png', '.gif', '.svg', '.webp', '.ico', '.tif', '.tiff', '.heic', '.bmp', '.avif'],
+  Videos: ['.mp4', '.mkv', '.avi', '.mov', '.wmv', '.webm', '.flv', '.m4v'],
+  Audio: ['.mp3', '.wav', '.flac', '.aac', '.ogg', '.m4a'],
+  Documents: ['.pdf', '.doc', '.docx', '.txt', '.rtf', '.odt', '.xls', '.xlsx', '.csv', '.ppt', '.pptx', '.md'],
+  Code: ['.js', '.cjs', '.mjs', '.ts', '.tsx', '.jsx', '.json', '.yaml', '.yml', '.xml', '.html', '.css', '.scss', '.less', '.py', '.java', '.c', '.cpp', '.cs', '.go', '.rs', '.php', '.rb', '.sh', '.ps1', '.sql'],
+  Archives: ['.zip', '.rar', '.7z', '.tar', '.gz', '.bz2', '.xz'],
+  Installers: ['.exe', '.msi', '.apk', '.dmg', '.pkg', '.deb', '.rpm'],
+  Fonts: ['.ttf', '.otf', '.woff', '.woff2'],
+  Design: ['.fig', '.sketch', '.xd', '.psd', '.ai'],
+  Data: ['.db', '.sqlite', '.sqlite3', '.parquet', '.log'],
+};
+
+const NAME_RULES = [
+  { folder: 'Screenshots', patterns: [/^screenshot/i, /^screen[-_ ]?shot/i] },
+  { folder: 'Installers', patterns: [/\bsetup\b/i, /\binstall/i, /\bupdate\b/i] },
+  { folder: 'Backups', patterns: [/\bbackup\b/i, /\.bak$/i, /copy/i] },
+  { folder: 'Notes', patterns: [/\bnote/i, /\bnotes\b/i, /\bmeeting\b/i, /\btodo\b/i] },
+  { folder: 'Invoices', patterns: [/\binvoice\b/i, /\breceipt\b/i, /\bbill\b/i] },
+  { folder: 'Presentations', patterns: [/\bpresentation\b/i, /\bslides?\b/i, /\bpitch\b/i] },
+];
+
+module.exports = {
+  APP_FOLDER,
+  CATEGORY_RULES,
+  INTERNAL_FILES,
+  MANIFEST_PREFIX,
+  NAME_RULES,
+  VERSION,
+};

package/src/core/filesystem.js

@@ -0,0 +1,25 @@
+const fs = require('fs');
+const path = require('path');
+
+function ensureDirectory(dirPath, dryRun) {
+  if (dryRun || fs.existsSync(dirPath)) return;
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function getSafeDestination(destinationDir, fileName) {
+  const parsed = path.parse(fileName);
+  let candidate = fileName;
+  let counter = 1;
+
+  while (fs.existsSync(path.join(destinationDir, candidate))) {
+    candidate = `${parsed.name}(${counter})${parsed.ext}`;
+    counter += 1;
+  }
+
+  return path.join(destinationDir, candidate);
+}
+
+module.exports = {
+  ensureDirectory,
+  getSafeDestination,
+};

package/src/core/manifest.js

@@ -0,0 +1,46 @@
+const fs = require('fs');
+const path = require('path');
+const { APP_FOLDER, MANIFEST_PREFIX } = require('../constants');
+
+function getAppDir(targetDir) {
+  return path.join(targetDir, APP_FOLDER);
+}
+
+function getTimestampId() {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+function saveManifest(targetDir, payload) {
+  const appDir = getAppDir(targetDir);
+  if (!fs.existsSync(appDir)) {
+    fs.mkdirSync(appDir, { recursive: true });
+  }
+
+  const manifestPath = path.join(appDir, `${MANIFEST_PREFIX}${getTimestampId()}.json`);
+  fs.writeFileSync(manifestPath, JSON.stringify(payload, null, 2));
+  return manifestPath;
+}
+
+function readManifest(manifestPath) {
+  return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+}
+
+function getLatestManifest(targetDir) {
+  const appDir = getAppDir(targetDir);
+  if (!fs.existsSync(appDir)) return null;
+
+  const candidates = fs
+    .readdirSync(appDir)
+    .filter((file) => file.startsWith(MANIFEST_PREFIX) && file.endsWith('.json'))
+    .sort();
+
+  if (candidates.length === 0) return null;
+  return path.join(appDir, candidates[candidates.length - 1]);
+}
+
+module.exports = {
+  getAppDir,
+  getLatestManifest,
+  readManifest,
+  saveManifest,
+};

package/src/core/organizer.js

@@ -0,0 +1,174 @@
+const fs = require('fs');
+const path = require('path');
+const { APP_FOLDER, INTERNAL_FILES, VERSION } = require('../constants');
+const { ensureDirectory, getSafeDestination } = require('./filesystem');
+const { saveManifest } = require('./manifest');
+const { writeReport } = require('./report');
+const { buildDestinationFolder, getManagedFolders } = require('./rules');
+const { ensureRelative } = require('../utils/paths');
+const { isHidden, matchesPattern } = require('../utils/patterns');
+
+function createStats() {
+  return {
+    scanned: 0,
+    moved: 0,
+    skipped: 0,
+    errors: 0,
+    categories: {},
+    moves: [],
+  };
+}
+
+function collectFiles(rootDir, options, stats) {
+  const files = [];
+  const destinationFolders = getManagedFolders();
+  destinationFolders.add(APP_FOLDER);
+
+  function walk(currentDir) {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const absolutePath = path.join(currentDir, entry.name);
+      const relativePath = path.relative(rootDir, absolutePath) || entry.name;
+
+      if (!options.includeHidden && isHidden(entry.name)) {
+        if (options.verbose) console.log(`skip hidden: ${relativePath}`);
+        stats.skipped += 1;
+        continue;
+      }
+
+      if (matchesPattern(entry.name, options.excludePatterns) || matchesPattern(relativePath, options.excludePatterns)) {
+        if (options.verbose) console.log(`skip excluded: ${relativePath}`);
+        stats.skipped += 1;
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        if (destinationFolders.has(entry.name)) {
+          if (options.verbose) console.log(`skip managed folder: ${relativePath}`);
+          stats.skipped += 1;
+          continue;
+        }
+
+        if (options.recursive) {
+          walk(absolutePath);
+        } else if (options.verbose) {
+          console.log(`skip subfolder: ${relativePath}`);
+        }
+        continue;
+      }
+
+      files.push({ absolutePath, relativePath, name: entry.name });
+    }
+  }
+
+  walk(rootDir);
+  return files;
+}
+
+function tidyDirectory(targetDir, options) {
+  const stats = createStats();
+  const files = collectFiles(targetDir, options, stats);
+
+  console.log(`folder-tidy ${VERSION}`);
+  console.log(`command: tidy`);
+  console.log(`target: ${targetDir}`);
+  console.log(`mode: ${options.mode}${options.dryRun ? ' (dry run)' : ''}`);
+  console.log(`recursive: ${options.recursive ? 'yes' : 'no'}`);
+  console.log('');
+
+  for (const file of files) {
+    stats.scanned += 1;
+
+    if (targetDir === process.cwd() && INTERNAL_FILES.has(file.name)) {
+      if (options.verbose) console.log(`skip project file: ${file.name}`);
+      stats.skipped += 1;
+      continue;
+    }
+
+    let fileStats;
+    try {
+      fileStats = fs.statSync(file.absolutePath);
+    } catch (error) {
+      console.error(`failed to read file stats: ${file.relativePath}`);
+      stats.errors += 1;
+      continue;
+    }
+
+    const folderName = buildDestinationFolder(file.name, fileStats, options.mode);
+    const destinationDir = path.join(targetDir, folderName);
+
+    if (path.dirname(file.absolutePath) === destinationDir) {
+      if (options.verbose) console.log(`skip already organized: ${file.relativePath}`);
+      stats.skipped += 1;
+      continue;
+    }
+
+    const destinationPath = getSafeDestination(destinationDir, file.name);
+    const relativeDestination = ensureRelative(targetDir, destinationPath);
+
+    try {
+      ensureDirectory(destinationDir, options.dryRun);
+
+      if (!options.dryRun) {
+        fs.renameSync(file.absolutePath, destinationPath);
+      }
+
+      console.log(`${options.dryRun ? 'plan' : 'move'}: ${file.relativePath} -> ${relativeDestination}`);
+      stats.moved += 1;
+      stats.categories[folderName] = (stats.categories[folderName] || 0) + 1;
+      stats.moves.push({
+        from: file.relativePath,
+        to: relativeDestination,
+      });
+    } catch (error) {
+      console.error(`failed: ${file.relativePath} -> ${relativeDestination}`);
+      if (options.verbose) console.error(error.message);
+      stats.errors += 1;
+    }
+  }
+
+  let manifestPath = null;
+  if (!options.dryRun && !options.noManifest && stats.moves.length > 0) {
+    manifestPath = saveManifest(targetDir, {
+      version: VERSION,
+      command: 'tidy',
+      target: targetDir,
+      mode: options.mode,
+      recursive: options.recursive,
+      includeHidden: options.includeHidden,
+      excludePatterns: options.excludePatterns,
+      createdAt: new Date().toISOString(),
+      moves: stats.moves,
+    });
+  }
+
+  let reportPath = null;
+  if (options.reportPath) {
+    reportPath = writeReport(options.reportPath, {
+      version: VERSION,
+      command: 'tidy',
+      target: targetDir,
+      options: {
+        mode: options.mode,
+        dryRun: options.dryRun,
+        recursive: options.recursive,
+        includeHidden: options.includeHidden,
+        excludePatterns: options.excludePatterns,
+      },
+      stats,
+      manifestPath,
+      createdAt: new Date().toISOString(),
+    });
+  }
+
+  return {
+    stats,
+    manifestPath,
+    reportPath,
+  };
+}
+
+module.exports = {
+  tidyDirectory,
+};

package/src/core/report.js

@@ -0,0 +1,19 @@
+const fs = require('fs');
+const path = require('path');
+const { normalizePath } = require('../utils/paths');
+
+function writeReport(reportPath, payload) {
+  const resolved = normalizePath(reportPath);
+  const parentDir = path.dirname(resolved);
+
+  if (!fs.existsSync(parentDir)) {
+    fs.mkdirSync(parentDir, { recursive: true });
+  }
+
+  fs.writeFileSync(resolved, JSON.stringify(payload, null, 2));
+  return resolved;
+}
+
+module.exports = {
+  writeReport,
+};

package/src/core/rules.js

@@ -0,0 +1,48 @@
+const path = require('path');
+const { CATEGORY_RULES, NAME_RULES } = require('../constants');
+
+function getDateFolder(fileStats) {
+  const date = fileStats.mtime;
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  return `${year}-${month}`;
+}
+
+function getTypeFolder(fileName) {
+  const extension = path.extname(fileName).toLowerCase();
+  for (const [folder, extensions] of Object.entries(CATEGORY_RULES)) {
+    if (extensions.includes(extension)) {
+      return folder;
+    }
+  }
+  return extension ? 'Others' : 'No Extension';
+}
+
+function getNameFolder(fileName) {
+  for (const rule of NAME_RULES) {
+    if (rule.patterns.some((pattern) => pattern.test(fileName))) {
+      return rule.folder;
+    }
+  }
+  return getTypeFolder(fileName);
+}
+
+function buildDestinationFolder(fileName, fileStats, mode) {
+  if (mode === 'date') return getDateFolder(fileStats);
+  if (mode === 'name') return getNameFolder(fileName);
+  return getTypeFolder(fileName);
+}
+
+function getManagedFolders() {
+  return new Set([
+    ...Object.keys(CATEGORY_RULES),
+    ...NAME_RULES.map((rule) => rule.folder),
+    'Others',
+    'No Extension',
+  ]);
+}
+
+module.exports = {
+  buildDestinationFolder,
+  getManagedFolders,
+};

package/src/utils/paths.js

@@ -0,0 +1,14 @@
+const path = require('path');
+
+function normalizePath(inputPath) {
+  return path.resolve(inputPath);
+}
+
+function ensureRelative(baseDir, targetPath) {
+  return path.relative(baseDir, targetPath).split(path.sep).join('/');
+}
+
+module.exports = {
+  ensureRelative,
+  normalizePath,
+};

package/src/utils/patterns.js

@@ -0,0 +1,17 @@
+function globToRegex(pattern) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`^${escaped.replace(/\*/g, '.*')}$`, 'i');
+}
+
+function matchesPattern(value, patterns) {
+  return patterns.some((pattern) => globToRegex(pattern).test(value));
+}
+
+function isHidden(name) {
+  return name.startsWith('.');
+}
+
+module.exports = {
+  matchesPattern,
+  isHidden,
+};