From eba55a40804f28e5015e5c8dc0a8a48ed37293c6 Mon Sep 17 00:00:00 2001 From: jessikitty Date: Tue, 23 Dec 2025 01:13:16 +1100 Subject: [PATCH] Add comprehensive README documentation - Usage instructions for 3 different methods - Complete safety features explanation - Expected output examples - Troubleshooting guide - Backup and restore procedures --- README.md | 279 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 279 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..111b880 --- /dev/null +++ b/README.md @@ -0,0 +1,279 @@ +# Home Assistant Chore Cleanup Script + +Automatically removes unused chore-related entities from your Home Assistant YAML configuration files. + +## 🎯 What It Does + +This script identifies and removes **46 unused entities** from your Home Assistant configuration: + +- **19 Input Booleans**: Unused task tracking booleans (personal desk/room cleaning, generic tasks) +- **7 Duplicate Scripts**: Old naming convention (`complete_task_*` versions) +- **3 Generic Scripts**: Unused completion scripts + +## ✅ Safety Features + +- **Automatic Backups**: Creates timestamped backups before making ANY changes +- **Restore Script**: Generates a one-click restore script in case you need to undo +- **Dry-run Capable**: Review what will be removed before committing +- **Error Handling**: Continues even if some files fail, reports all errors at end + +## 📋 What Gets Removed + +### Input Booleans (19 items) +``` +task_lou_clean_desk_pending +task_jess_clean_desk_pending +task_william_clean_desk_pending +task_xander_clean_desk_pending +task_bella_clean_desk_pending +task_lou_clean_room_pending +task_jess_clean_room_pending +task_william_clean_room_pending +task_xander_clean_room_pending +task_bella_clean_room_pending +task_tidy_lounge_pending +task_vacuum_room_pending +task_get_school_ready_pending +task_clean_desks_done_this_week +task_clean_rooms_done_this_week +task_tidy_lounge_done_this_week +task_tidy_kitchen_done_today +task_clean_dining_table_done_today +task_vacuum_room_done_today +``` + +### Scripts (10 items) +``` +complete_task_dishwasher_unload (duplicate) +complete_task_washing_machine_unload (duplicate) +complete_task_dryer_unload (duplicate) +complete_task_bins_out (duplicate) +complete_task_bins_in (duplicate) +complete_task_kitty_litter_clean (duplicate) +complete_task_kitty_litter_change (duplicate) +complete_tidy_lounge (unused) +complete_vacuum_room (unused) +complete_get_school_ready (unused) +``` + +## 🚀 Usage + +### Method 1: Run Directly on Home Assistant + +```bash +# SSH into your Home Assistant instance +ssh root@homeassistant.local + +# Copy the script to your config directory +# (You can upload via File Editor add-on or SCP) + +# Make it executable +chmod +x /config/ha_chore_cleanup.py + +# Run the script +python3 /config/ha_chore_cleanup.py +``` + +### Method 2: Run from Any Machine (with path) + +```bash +# If your Home Assistant config is mounted elsewhere +python3 ha_chore_cleanup.py /path/to/your/config +``` + +### Method 3: Via Home Assistant Terminal Add-on + +1. Install "Terminal & SSH" add-on +2. Upload script via File Editor +3. Run in terminal: +```bash +cd /config +python3 ha_chore_cleanup.py +``` + +## 📂 What Files Get Modified + +The script will search and modify these files if they exist: + +- `configuration.yaml` (if entities are defined inline) +- `input_boolean.yaml` or `input_booleans.yaml` +- `scripts.yaml` or `script.yaml` +- `helpers.yaml` (if it exists) +- Any files in `packages/` directory containing the target entities + +## 🔄 Backup Location + +Backups are saved to: +``` +/config/backups/cleanup_YYYYMMDD_HHMMSS/ +``` + +Each backup directory contains: +- Original YAML files before modification +- `restore.sh` - One-click restoration script + +## ⚠️ Important Notes + +### What's KEPT (Safe to Keep) +The script **does NOT remove** these items because they're actively used: + +**Tracking Booleans** (used in automation conditions): +- `task_bella_clothes_done_today` +- `task_xander_clothes_done_today` +- `task_william_clothes_done_today` +- `task_handwash_dishes_done_today` +- `task_feed_chips_done_today` +- `task_feed_harper_done_today` +- `task_water_chips_done_today` +- `task_water_harper_done_today` +- `task_kitty_litter_clean_done_today` +- `task_kitty_litter_change_done_fortnight` + +These prevent duplicate task creation and are referenced in your automations. + +### Files with !include Directives +If the script encounters YAML files with `!include` or `!secret` directives, it will: +- Create a backup +- Skip automatic modification +- Report the file for manual review + +## 📊 Expected Output + +``` +====================================================================== +Home Assistant Chore Cleanup Script +====================================================================== +✓ Created backup directory: /config/backups/cleanup_20241223_150000 + +Processing configuration.yaml... + ✓ Backed up: configuration.yaml + Removed 5 input_boolean entries + Removed 3 script entries + ✓ Saved: configuration.yaml + +Processing input_boolean.yaml... + ✓ Backed up: input_boolean.yaml + ✓ Removed 14 input_boolean entries + ✓ Saved: input_boolean.yaml + +Processing scripts.yaml... + ✓ Backed up: scripts.yaml + ✓ Removed 7 script entries + ✓ Saved: scripts.yaml + +====================================================================== +CLEANUP SUMMARY +====================================================================== + +✓ Backups saved to: /config/backups/cleanup_20241223_150000 + +📋 Input Booleans Removed: 19 + - task_bella_clean_desk_pending + - task_clean_desks_done_this_week + [... full list ...] + +📜 Scripts Removed: 10 + - complete_get_school_ready + - complete_task_bins_in + [... full list ...] + +====================================================================== +NEXT STEPS: +====================================================================== +1. Review the changes in your YAML files +2. Run 'ha core check' to verify configuration +3. If everything looks good, restart Home Assistant +4. If issues occur, restore from backups +====================================================================== +``` + +## 🔧 Post-Cleanup Steps + +### 1. Verify Configuration +```bash +# Check configuration is valid +ha core check +``` + +### 2. Review Changes (Optional) +```bash +# Compare backup to current +diff /config/backups/cleanup_YYYYMMDD_HHMMSS/scripts.yaml /config/scripts.yaml +``` + +### 3. Restart Home Assistant +```bash +ha core restart +``` + +### 4. Verify Everything Works +- Check your Dailies dashboard (dashboard-chores) +- Test a few task completions +- Check for any errors in logs + +## 🔙 How to Restore (If Needed) + +### Option 1: Use the Restore Script +```bash +cd /config/backups/cleanup_YYYYMMDD_HHMMSS +./restore.sh +ha core restart +``` + +### Option 2: Manual Restore +```bash +# Copy backup files back +cp /config/backups/cleanup_YYYYMMDD_HHMMSS/*.yaml /config/ +ha core restart +``` + +## 🐛 Troubleshooting + +### "Permission Denied" +```bash +chmod +x ha_chore_cleanup.py +``` + +### "Module 'yaml' not found" +```bash +pip3 install pyyaml +``` + +### Configuration Check Fails After Cleanup +1. Don't panic - your backups are safe +2. Run the restore script +3. Review what was removed +4. Report any issues + +### Script Reports Errors +- Check the error messages in the summary +- Review those specific files manually +- The script continues even if some files fail + +## 📝 Logs & Debugging + +The script outputs detailed information about: +- Which files it's processing +- How many items it removed from each file +- Any errors encountered +- Full list of removed items + +All output is also printed to console for your review. + +## 🤝 Support + +If you encounter issues: +1. Check the backup directory - your files are safe +2. Review the error messages +3. Restore from backup if needed +4. Report the issue with the full output + +## 📜 License + +Created for Jess's Home Assistant setup +Use freely, modify as needed + +--- + +**Last Updated**: December 23, 2024 +**Version**: 1.0.0