From 8af321094fc58717c001774f20eec4197aecd203 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Sun, 10 May 2026 17:52:42 -0400 Subject: [PATCH] possible hot reload track. --- conductor/tracks.md | 8 +++ .../hot_reload_python_20260510/metadata.json | 10 ++++ .../tracks/hot_reload_python_20260510/plan.md | 37 ++++++++++++ .../tracks/hot_reload_python_20260510/spec.md | 56 +++++++++++++++++++ 4 files changed, 111 insertions(+) create mode 100644 conductor/tracks/hot_reload_python_20260510/metadata.json create mode 100644 conductor/tracks/hot_reload_python_20260510/plan.md create mode 100644 conductor/tracks/hot_reload_python_20260510/spec.md diff --git a/conductor/tracks.md b/conductor/tracks.md index c0c7dc2..6f53170 100644 --- a/conductor/tracks.md +++ b/conductor/tracks.md @@ -44,6 +44,14 @@ This file tracks all major tracks for the project. Each track has its own detail --- +## Hot Reload Feature + +1. [ ] **Track: Hot Reload Python Codebase** + *Link: [./tracks/hot_reload_python_20260510/](./tracks/hot_reload_python_20260510/)* + *Goal: Add file system watching capability to automatically invalidate cached AST parse trees and summaries when source files change on disk.* + +--- + ## Phase 5: Codebase Curation *Initialized: 2026-05-07* diff --git a/conductor/tracks/hot_reload_python_20260510/metadata.json b/conductor/tracks/hot_reload_python_20260510/metadata.json new file mode 100644 index 0000000..f4d8e13 --- /dev/null +++ b/conductor/tracks/hot_reload_python_20260510/metadata.json @@ -0,0 +1,10 @@ +{ + "id": "hot_reload_python_20260510", + "title": "Hot Reload Python Codebase", + "type": "feature", + "status": "planned", + "priority": "medium", + "created": "2026-05-10", + "depends_on": [], + "blocks": [] +} \ No newline at end of file diff --git a/conductor/tracks/hot_reload_python_20260510/plan.md b/conductor/tracks/hot_reload_python_20260510/plan.md new file mode 100644 index 0000000..2e38e11 --- /dev/null +++ b/conductor/tracks/hot_reload_python_20260510/plan.md @@ -0,0 +1,37 @@ +# Implementation Plan: Hot Reload Python Codebase + +## Phase 1: Core File Watcher Infrastructure +Focus: File system watcher using watchgod with subprocess restart + +- [ ] Task 1.1: Add `watchgod` dependency to pyproject.toml +- [ ] Task 1.2: Create `src/hot_reload.py` with `HotReloadWatcher` class using watchgod +- [ ] Task 1.3: Implement debounced file change handler (300ms window) +- [ ] Task 1.4: Implement subprocess restart logic with same CLI arguments +- [ ] Task 1.5: Handle graceful shutdown before restart +- [ ] Task 1.6: Write tests for HotReloadWatcher in `tests/test_hot_reload.py` +- [ ] Task 1.7: Write tests for subprocess restart behavior + +## Phase 2: CLI/Entry Point Integration +Focus: Wire hot reload into application entry points + +- [ ] Task 2.1: Add `--watch` CLI flag to gui_2.py or pyproject.toml scripts +- [ ] Task 2.2: Add `MANUAL_SLOP_WATCH=1` environment variable support +- [ ] Task 2.3: Add hot reload status indicator in GUI (optional) +- [ ] Task 2.4: Add logging when restart is triggered +- [ ] Task 2.5: Write integration tests for CLI flag behavior + +## Phase 3: Path Configuration +Focus: Configure watch patterns for the Manual Slop project structure + +- [ ] Task 3.1: Watch `src/**/*.py` for application code changes +- [ ] Task 3.2: Watch `scripts/**/*.py` for helper script changes +- [ ] Task 3.3: Watch root `*.py` files (gui_2.py, etc.) +- [ ] Task 3.4: Exclude `tests/**/*.py` and `logs/**/*` from watch +- [ ] Task 3.5: Write tests for path filtering behavior + +## Phase 4: Verification +Focus: Full regression testing and user manual verification + +- [ ] Task 4.1: Run pytest on tests/test_hot_reload.py +- [ ] Task 4.2: Manual verification - modify .py file, verify app restarts +- [ ] Task 4.3: Conductor - User Manual Verification (Protocol in workflow.md) \ No newline at end of file diff --git a/conductor/tracks/hot_reload_python_20260510/spec.md b/conductor/tracks/hot_reload_python_20260510/spec.md new file mode 100644 index 0000000..4ddace8 --- /dev/null +++ b/conductor/tracks/hot_reload_python_20260510/spec.md @@ -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.) \ No newline at end of file