From d760fa81bc9d9ffe9c3374974fb8d969c77b4920 Mon Sep 17 00:00:00 2001 From: bartool Date: Fri, 6 Mar 2026 19:10:50 +0100 Subject: [PATCH] add gemini context --- gemini.md | 457 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 457 insertions(+) create mode 100644 gemini.md diff --git a/gemini.md b/gemini.md new file mode 100644 index 0000000..54194e2 --- /dev/null +++ b/gemini.md @@ -0,0 +1,457 @@ +# gemini.md + +## Project Overview + +This project is a **Windows background application written in Python** that automatically monitors a selected **Git repository directory** and performs commits whenever files change. + +The application is intended for environments where users are **not expected to interact with Git manually** (e.g. CNC operators). All commits are handled automatically. + +The application runs **silently in the background** with a **system tray icon** and **Windows notifications**. + +The final application must be packaged using **PyInstaller as a single executable file** with **no console window**. + +--- + +# Core Features + +## Background Operation + +* The application runs in the background. +* No console window should be visible. +* A **system tray icon** must be present in the Windows taskbar notification area. + +The tray icon menu must contain: + +* **Select Repository Folder** +* **Exit Application** + +--- + +# Git Monitoring Behavior + +The application monitors a selected folder that contains a **Git repository**. + +Every filesystem change triggers an automatic commit. + +The following actions must be detected: + +* File created +* File modified +* File deleted +* File renamed / moved + +Each change should produce a commit with message: + +``` +f"{action}: {file}" +``` + +Examples: + +``` +create: program.nc +modify: toolpath.nc +delete: old_part.nc +rename: part_v1.nc -> part_v2.nc +``` + +Commits must be executed automatically using Git. + +If the directory is not a Git repository, the application should: + +* notify the user +* not start monitoring + +--- + +# Windows Notifications + +The application should generate **Windows toast notifications** for: + +* repository monitoring started +* repository monitoring stopped +* commit created +* errors + +Example notification: + +``` +Git Monitor +modify: program.nc committed +``` + +--- + +# Logging + +The application must write logs to a file. + +Log file requirements: + +* log filename: `git_monitor.log` +* stored in the application directory +* log levels: + + * INFO + * WARNING + * ERROR + +Logged events: + +* application start +* repository selected +* detected file change +* git commit executed +* errors and exceptions + +--- + +# System Tray UI + +The application must provide a **tray icon**. + +Right-click menu: + +``` +Git Monitor +──────────── +Select Repository +Exit +``` + +Behavior: + +### Select Repository + +Opens a folder selection dialog. + +Once selected: + +* verify `.git` directory exists +* start monitoring + +### Exit + +Stops monitoring and terminates the application. + +--- + +# Application Architecture + +The application must be **modular** and structured using classes. + +Recommended project structure: + +``` +git_monitor/ + +main.py +tray_app.py +git_manager.py +file_watcher.py +notifier.py +config.py +logger.py +``` + +--- + +# Modules + +## main.py + +Application entry point. + +Responsibilities: + +* initialize logging +* initialize tray application +* start event loop + +Main class: + +``` +Application +``` + +--- + +# tray_app.py + +Handles the **system tray icon and menu**. + +Recommended library: + +``` +pystray +``` + +Responsibilities: + +* create tray icon +* handle menu events +* start/stop monitoring + +Main class: + +``` +TrayApp +``` + +Methods: + +``` +select_repository() +start_monitoring() +stop_monitoring() +exit_app() +``` + +--- + +# file_watcher.py + +Responsible for filesystem monitoring. + +Recommended library: + +``` +watchdog +``` + +Main class: + +``` +RepositoryWatcher +``` + +Responsibilities: + +* monitor filesystem events +* translate events to actions +* send events to GitManager + +Handled events: + +``` +on_created +on_modified +on_deleted +on_moved +``` + +--- + +# git_manager.py + +Handles all Git operations. + +Recommended library: + +``` +GitPython +``` + +Main class: + +``` +GitManager +``` + +Responsibilities: + +* validate repository +* stage changed files +* perform commits + +Methods: + +``` +is_git_repository(path) +commit_change(action, file) +``` + +Commit format: + +``` +f"{action}: {file}" +``` + +--- + +# notifier.py + +Responsible for Windows notifications. + +Recommended library: + +``` +win10toast +``` + +Main class: + +``` +Notifier +``` + +Methods: + +``` +notify(title, message) +``` + +--- + +# logger.py + +Handles application logging. + +Use Python logging module. + +Features: + +* file logging +* timestamp +* log levels + +Log format example: + +``` +2026-03-06 18:32:11 INFO Repository monitoring started +2026-03-06 18:32:20 INFO modify: program.nc committed +``` + +--- + +# config.py + +Stores application configuration. + +Possible stored data: + +* last used repository path + +Config file format: + +``` +config.json +``` + +Example: + +``` +{ + "repository_path": "C:/cnc/programs" +} +``` + +--- + +# Packaging + +The application must be packaged using **PyInstaller**. + +Requirements: + +* single executable +* no console window + +Example build command: + +``` +pyinstaller --onefile --noconsole main.py +``` + +--- + +# Error Handling + +The application must gracefully handle: + +* invalid repository path +* git errors +* filesystem watcher errors +* missing permissions + +Errors must: + +* be logged +* generate a Windows notification + +--- + +# Performance Considerations + +The application should: + +* avoid duplicate commits for rapid file changes +* debounce filesystem events if necessary +* run with minimal CPU usage + +--- + +# Recommended Python Libraries + +``` +watchdog +GitPython +pystray +pillow +win10toast +``` + +--- + +# Example Workflow + +1. Application starts +2. Tray icon appears +3. User selects repository +4. Monitoring begins +5. User edits a file +6. File watcher detects modification +7. GitManager stages file +8. Commit created automatically +9. Notification appears +10. Event logged + +--- + +# Future Improvements + +Possible future features: + +* commit batching +* ignore patterns (.gitignore support) +* commit history viewer +* push to remote repository +* repository auto-detection +* configuration GUI +* multiple repository support + +--- + +# Coding Style + +Requirements: + +* Python 3.11+ +* object-oriented design +* clear class responsibilities +* structured logging +* minimal global state + +--- + +# Summary + +The goal is to create a **lightweight background Windows application** that automatically commits changes in a Git repository without requiring the user to interact with Git. + +The system should be: + +* stable +* silent +* automatic +* easy to deploy (single EXE) +* minimal UI (tray only)