Prepare v0.2.0 Release Candidate 1

[DOS1986]

Summary

This pull request prepares Documents Organizer v0.2.0 Release Candidate 1.

v0.2.0 is a major update that redesigns the application's file organization behavior, improves filesystem safety, refactors the application architecture, introduces lazy-loaded folder browsing, expands automated testing, and adds a repeatable Windows release build pipeline.

The release candidate is versioned as:

• Application version: 0.2.0rc1
• Release version: 0.2.0-rc1
• Windows file version: 0.2.0.1

---

Highlights

New Organization Structure

Files are now organized using a date-first structure:

Selected Folder/
└── YYYY-MM-DD/
    ├── pdf/
    ├── jpg/
    ├── txt/
    ├── zip/
    └── other/

The date is based on the file's modified date.

Files without extensions are placed in other.

Nested File Centralization

Files found in nested directories are centralized into the selected operation target's date/type hierarchy.

Original source directories are intentionally preserved, even when they become empty.

Safer Duplicate Handling

Existing destination files are not intentionally overwritten.

Duplicate filenames are preserved using numbered suffixes:

report.pdf
report (1).pdf
report (2).pdf

Collision protection is used by both Organize and Flatten operations.

Safer Flattening

Flatten now operates only on recognized organizer-generated date/type structures.

It:

• moves organized files back into the selected root
• preserves duplicate filenames
• supports extensionless files
• removes only empty organizer-generated directories
• preserves unexpected content
• supports cooperative cancellation

Flatten reverses the organizer-generated structure, but it is not a full undo system and does not restore files to their original nested source directories.

---

User Interface

The main application interface has been substantially reorganized and refactored.

Changes include:

• redesigned main application layout
• selected Root Folder and Operation Target summary
• reusable toolbar and menu components
• activity log component
• status bar and progress indicator
• reusable application header
• centralized ttk styling
• system tray integration
• safe application shutdown behavior

Lazy-Loaded Folder Browser

The Folder Browser now loads directory contents on demand.

Selecting a root folder loads only its immediate directories. Nested folders are discovered when expanded instead of recursively scanning the entire directory tree during initial load.

Nested selections are also restored during refresh without loading unrelated branches.

---

Architecture

The original large MainWindow implementation has been broken into focused application layers.

Services

Filesystem operations are isolated in:

documents_organizer/services/

including:

• organizer
• flattener

Controllers

Background operation management is isolated in:

documents_organizer/controllers/operation_controller.py

The controller manages:

• worker threads
• operation lifecycle
• busy state
• concurrent-operation prevention
• flatten cancellation
• worker-to-Tkinter result dispatch
• clean shutdown

Presenters

Operation result formatting is isolated in:

documents_organizer/presenters/operation_presenter.py

This keeps user-facing message generation separate from Tkinter rendering.

UI Components

Reusable UI components now include:

• ActivityLog
• FolderBrowser
• FolderSummary
• Header
• MenuBar
• StatusBar
• Toolbar

System tray behavior and application styling have also been moved out of MainWindow.

---

Testing

The automated test suite has been expanded significantly.

Coverage includes:

• safe file movement
• duplicate filename handling
• ignored system files
• modified-date organization
• extension/type organization
• extensionless files
• nested file centralization
• already-organized file detection
• flatten behavior
• safe directory cleanup
• flatten cancellation
• operation controller lifecycle
• concurrent-operation prevention
• operation result presentation
• lazy-loaded folder browsing
• nested selection restoration
• deleted-selection fallback
• resource path handling
• complete organize-to-flatten workflows
• duplicate preservation across round trips
• extensionless file preservation
• repeated Organize safety
• repeated Flatten safety

Filesystem tests use temporary directories rather than real user files.

---

Windows Packaging

v0.2.0 adds reproducible Windows packaging using PyInstaller.

Release preparation now includes:

• committed PyInstaller specification
• bundled application image resources
• GUI build without a console window
• Windows executable icon
• Windows version metadata
• product and file version validation
• repeatable PowerShell release build
• versioned Windows x64 ZIP archives
• SHA-256 checksum generation

The release build script validates version consistency between:

documents_organizer/__init__.py
pyproject.toml
Windows ProductVersion
Windows FileVersion
FixedFileInfo filevers
FixedFileInfo prodvers

It also validates the metadata embedded in the finished executable.

---

Continuous Integration

GitHub Actions workflows have been added for:

Tests

• Python 3.12
• Python 3.13
• source compilation
• complete pytest suite

Windows Build

• Windows x64 clean build
• full release build script
• PyInstaller packaging
• executable metadata validation
• release ZIP generation
• SHA-256 generation
• downloadable workflow artifacts

---

Documentation

The README has been rewritten for v0.2.0 and now documents:

• date-first organization
• nested file behavior
• duplicate protection
• extensionless files
• flatten limitations
• lazy-loaded folder browsing
• Root Folder vs. Operation Target
• filesystem safety
• current architecture
• testing
• Windows packaging
• current platform support
• future roadmap

Old screenshots representing the previous application interface have been removed from the active documentation until updated v0.2.0 screenshots are captured.

---

Release Candidate Validation

Local validation completed:

• Application compiles successfully
• Complete automated test suite passes
• PyInstaller Windows build succeeds
• Packaged application launches successfully
• Windows executable metadata is correct
• Application icon loads correctly
• System tray Show and Quit work correctly
• Lazy-loaded folder browser works in packaged application
• Organize works in packaged application
• Flatten works in packaged application
• Release ZIP works when extracted outside the repository
• SHA-256 release checksum is generated

GitHub validation:

• Python 3.12 CI passes
• Python 3.13 CI passes
• Windows x64 build passes
• GitHub-generated Windows artifact smoke-tested

---

Notes

This PR prepares the first release candidate rather than the final v0.2.0 release.

After this PR passes CI and the GitHub-generated Windows artifact is validated, the branch can be merged into main and tagged as:

v0.2.0-rc1

Any issues discovered during release-candidate testing will be addressed before the final v0.2.0 release.