# 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 or plyer
```

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"
}
```

# Project Status: Completed

The application is fully implemented and tested for Windows 11 background operation.

# Current Architecture (Finalized)

The project is structured as a proper Python package to ensure compatibility with PyInstaller and robust path handling.

```
auto-git/
├── run.py                 # Main entry point for Python/PyInstaller
├── git_monitor/           # Main package
│   ├── __init__.py        # Package marker
│   ├── main.py            # Application lifecycle
│   ├── tray_app.py        # System tray (pystray) + UI (tkinter)
│   ├── git_manager.py     # Git operations (GitPython)
│   ├── file_watcher.py    # Filesystem monitoring (watchdog)
│   ├── notifier.py        # Windows notifications (plyer + win10toast fallback)
│   ├── config.py          # Persistent configuration (config.json)
│   ├── logger.py          # Application logging (git_monitor.log)
│   └── requirements.txt   # Dependency list
└── .gitignore             # Project ignore rules
```

---

# Implemented Solutions & Fixes

### 1. UI Responsive Fix (Windows 11)
To prevent the application from freezing during folder selection:
* **Threading**: `pystray` runs in a separate background thread.
* **Main Loop**: `tkinter.mainloop()` runs in the main thread to handle system dialogs properly.
* **Non-blocking Dialogs**: Folder selection is scheduled via `root.after(0, ...)` to ensure it doesn't block the tray icon.

### 2. PyInstaller Compatibility
* **Package Imports**: All internal imports use absolute paths (e.g., `from git_monitor.logger import ...`).
* **Path Management**: `logger.py` and `config.py` use `sys.frozen` detection to ensure data files are always located relative to the `.exe` file, not temporary directories.
* **Notification Robustness**: Added a fallback mechanism in `notifier.py`. If `plyer` fails to find a platform implementation (common in isolated environments), it automatically switches to `win10toast`.

---

# Build Instructions

To generate the standalone executable, use the following command from the project root:

```powershell
pyinstaller.exe --onefile --noconsole --name git-monitor --hidden-import="plyer.platforms.win.notification" run.py
```

### Build Parameters:
* `--onefile`: Packages everything into a single `.exe`.
* `--noconsole`: Hides the command prompt window during execution.
* `--hidden-import`: Manually includes the dynamic notification module for Windows.

---

# Runtime Files
* **Log File**: `git_monitor.log` (created in the same folder as the `.exe`).
* **Config File**: `config.json` (created in the same folder as the `.exe`).