possible hot reload track.

2026-05-10 17:52:42 -04:00
parent 4940913e36
commit 8af321094f
4 changed files with 111 additions and 0 deletions
@@ -0,0 +1,56 @@
+# Track Specification: Hot Reload Python Codebase
+
+## Overview
+
+Add file system watching capability to automatically reload/restart the Manual Slop application when source files are modified during development. This eliminates the manual stop/restart cycle when iterating on the codebase.
+
+## Current State Audit (as of 4940913e)
+
+### Already Implemented (DO NOT re-implement)
+
+- **gui_2.py**: Main application entry with `App` class, `run()` method, and imgui-bundle integration
+- **src/app_controller.py**: Application controller with state management
+- **pyproject.toml**: Project configuration with `[project.scripts]` for `manual-slop` entry point
+- **scripts/**: Helper scripts for various dev tasks
+
+### Gaps to Fill (This Track's Scope)
+
+1. **No hot reload mechanism**: No watchdog/inotify-based file watching to trigger app restart
+2. **Manual restarts required**: Developers must stop and restart the app after every code change
+3. **No dev iteration helper**: No integration with existing dev tooling (watchgod, hupper, or py --watch)
+
+## Goals
+
+1. Watch source files (*.py) in src/, scripts/, and root directories
+2. Automatically restart the running application when Python files change
+3. Provide a CLI flag or environment variable to enable/disable hot reload mode
+4. Debounce rapid file changes to prevent restart storms
+5. Preserve application state where possible during reload
+
+## Functional Requirements
+
+- File system watcher using `watchgod` (lightweight, pure Python, no C extensions)
+- Watch patterns: `src/**/*.py`, `scripts/**/*.py`, `*.py` in project root
+- Debounce window: 300ms to coalesce rapid file changes (e.g., save-all)
+- CLI flag: `--watch` or `MANUAL_SLOP_WATCH=1` environment variable
+- Graceful shutdown before restart, preserving logs
+- Restart via subprocess with same arguments
+
+## Non-Functional Requirements
+
+- Must not block the main thread
+- Memory overhead < 5MB
+- Restart latency < 1 second after file change settles
+- Compatible with Windows (PowerShell environment)
+
+## Architecture Reference
+
+- docs/guide_architecture.md#threading-model
+- pyproject.toml#project.scripts
+
+## Out of Scope
+
+- Hot reload within the same process (AST-level code swapping)
+- Watching non-Python files
+- Cross-machine or container-based file watching
+- IDE integration (VSCode, etc.)