Add File Watcher for External Command Control

[timothyfroehlich]

Summary

Add comprehensive external command interface for local development that allows sending commands to a running bot without restarting it.

🔧 Core Implementation

File Watcher System

• New module: src/file_watcher.py with cross-platform file monitoring using watchdog
• Integration: Seamless integration with existing console interface command processing
• Real-time: Commands processed immediately when appended to commands.txt
• Error handling: Graceful recovery from file operation errors

Local Development Infrastructure

• Console interface: src/console_discord.py for stdin/stdout Discord simulation
• Enhanced logging: src/local_logging.py with rotation, timestamps, and categorization
• Development entry point: src/local_dev.py supporting both console and file interfaces
• Production database: scripts/download_production_db.py using Litestream restore
• Test data setup: scripts/setup_test_cities.py with 10 major pinball cities

🚀 Usage

# Terminal 1: Start bot (keeps running indefinitely)
python src/local_dev.py

# Terminal 2: Send commands (no restart needed!)
echo "!list" >> commands.txt
echo ".status" >> commands.txt  
echo "!config poll_rate 15" >> commands.txt

# Terminal 3: Monitor all responses
tail -f logs/bot.log

✨ Key Benefits

• 🔄 No interruption: Bot continues monitoring while processing external commands
• 🎯 External control: Send commands from scripts, automation, or other terminals
• 📚 Command history: All commands preserved in commands.txt for reference
• 🌍 Cross-platform: Uses standard file operations (works everywhere)
• 🏢 Production data: Test with real monitoring targets (10 major cities pre-configured)
• 📊 Enhanced observability: Comprehensive logging with categories and rotation

📦 Dependencies

• Added watchdog library for cross-platform file monitoring
• Updated pyproject.toml with new dependency

📖 Documentation

• Main CLAUDE.md: Updated with external command interface section and examples
• LOCAL_DEVELOPMENT.md: Comprehensive guide with troubleshooting and workflows
• Directory CLAUDE.md files: Updated with new patterns and file descriptions
• Updated .gitignore: Excludes local development files from version control

🧪 Test Setup

Pre-configured with 10 major pinball cities for active testing:

• Portland, OR • Seattle, WA • Chicago, IL • Austin, TX • Denver, CO
• Los Angeles, CA • New York, NY • Boston, MA • Atlanta, GA • Phoenix, AZ

🔍 Technical Details

• Thread-safe: Uses asyncio.Queue for safe command passing between threads
• File watching: Monitors commands.txt for modifications using OS-level events
• Command processing: Reuses existing console interface logic for consistency
• Graceful shutdown: Proper cleanup of file watchers and async tasks
• Error resilience: Continues operating despite individual command failures

Ready for review and long-term testing! 🎉

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

📢 Thoughts on this report? Let us know!

[Copilot]

Pull Request Overview

Adds a file-based external command interface and ties it into the local development workflow, along with logging and documentation updates.

• Introduces src/file_watcher.py to monitor commands.txt and enqueue commands for the bot.
• Updates src/local_dev.py to start/stop the file watcher alongside the console interface.
• Enhances logging in src/local_logging.py and extends src/console_discord.py for full local-dev support.

Reviewed Changes

Copilot reviewed 13 out of 14 changed files in this pull request and generated 2 comments.

File	Description
src/file_watcher.py	New module: cross-platform file watcher enqueuing commands
src/local_dev.py	Local development entry point: starts your bot, console, and watcher
src/local_logging.py	Custom formatter, rotating file handler, and log level controls
src/console_discord.py	Console interface updates: stdin/stdout command processing

Comments suppressed due to low confidence (1)

src/file_watcher.py:237

• The new file watcher functionality isn't covered by existing tests. Consider adding unit tests that simulate file modifications and verify commands are queued and processed as expected.

async def create_file_watcher(command_processor: Callable[[str], Awaitable[None]], 

[cursor]

Bug: Incorrect Attribute Access Causes Errors

In the _show_monitoring_status method, the code accesses target.location_name when listing recent targets. This will cause an AttributeError because the MonitoringTarget model's attribute is display_name. Additionally, target.location_id can be null for geographic targets and should be handled to avoid displaying "None".

src/local_dev/console_discord.py#L279-L282

DisPinMap/src/local_dev/console_discord.py

Lines 279 to 282 in 9acb168

	for target in recent_targets:
	logger.info(
	f" - {target.location_name} (ID: {target.location_id})"
	)

Fix in Cursor • Fix in Web

---

Bug: Syntax Check Command Fails with Glob Patterns

The Python syntax check command python -m py_compile src/**/*.py is incorrect. The py_compile module expects individual file paths, not glob patterns, and the ** recursive glob may not be supported by all shells, leading to the check failing.

scripts/run_all_checks.sh#L69-L72

DisPinMap/scripts/run_all_checks.sh

Lines 69 to 72 in 9acb168

	# 1. Python syntax check
	run_check "Python Syntax Check" \
	"python -m py_compile src/**/*.py" \
	""

Fix in Cursor • Fix in Web

---

Was this report helpful? Give feedback by reacting with 👍 or 👎