macOS Advanced File Automator (Folder Action)

An enterprise-grade AppleScript automation designed for macOS to transform chaotic directories (like ~/Downloads) into a structured, self-organizing filesystem. This script leverages shell-level regex and atomic move operations to ensure data integrity and high-speed classification.

🚀 Core Architecture

The script operates on a six-stage processing pipeline:

1. I/O Stability Phase: Implements a 5-second delay to ensure asynchronous downloads or file copies are finalized before indexing.
2. Fault-Tolerant Isolation: Wrapped in a global try/catch block with detailed error logging to prevent script termination on single-file failures.
3. High-Entropy Taxonomy: Maps over 50+ file extensions into 9 distinct functional domains (Images, Docs, Dev, Fonts, etc.).
4. Regex Parsing Engine: Uses sed (Stream Editor) to perform non-linear pattern matching for media:
   • TV Series: Extracts metadata via [Ss]([0-9]{1,2})[Ee][0-9]{1,2} patterns.
   • Cinematic Assets: Identifies release years (19xx/20xx) and normalizes titles.
5. Atomic Move Protocol: Handles naming collisions by injecting Unix timestamps (dup_${ts}_) to prevent accidental overwrites.
6. Audit & Compliance: Generates real-time logs for every transaction and system error.

📂 Targeted Taxonomy

Category	Target Subfolder	Included Extensions
Media	1. Movies/Series or film/	mkv, mp4, avi, mov, webm, srt, ass
Photos	01_Photos	jpg, png, heic, webp, svg, gif, psd, ai
Documents	02_Documents	docx, xlsx, pptx, txt, rtf, epub, csv, md, lrc
PDFs	02_Documents/PDFs	pdf (Dedicated isolation)
Archives	03_Archives	zip, rar, 7z, tar, gz
Development	06_Development	py, js, html, css, json, cpp, go, sql, xml, .htaccess
System	08_Fonts	ttf, otf, woff, woff2

🛠 Installation

1. Environment: macOS only.
2. Deployment: * Open Script Editor.app.
   • Paste the source code.
   • Save as FileOrganizer.scpt in ~/Library/Scripts/Folder Action Scripts.
3. Activation:
   • Right-click your target folder (e.g., Downloads) -> Services -> Folder Actions Setup....
   • Attach FileOrganizer.scpt and ensure Enable Folder Actions is checked.

📝 Error & Audit Logs

The system maintains a dedicated 07_System_Logs directory within the target folder:

• audit_log.txt: Detailed history of every file movement.
• error_log.txt: Captured exceptions for debugging failed operations.