hass-sync

name	hass-sync
description	Maintains synchronization between src/hass folder and Home Assistant frontend source code. Verifies file locations, checks code matches upstream, and identifies unused code. Use when working with src/hass files, syncing Home Assistant code, or verifying code synchronization.

Home Assistant Code Synchronization

Maintains the src/hass folder which contains minimal code copied from Home Assistant frontend (home-assistant/frontend). Each file has a GitHub link comment at the top for reference.

Upstream Source

The upstream Home Assistant frontend is cloned locally at:

• Path: ../frontend/ (relative to device-card project root)
• Full path: /Users/patrickmasters/Desktop/src.nosync/homeassistant/frontend/

Keeping Upstream Updated

Before comparing, ensure the local frontend clone is up to date:

1. Check git status:

   cd ../frontend && git status
   

2. Check if behind upstream:

   cd ../frontend && git fetch && git status
   

3. Update if needed:

   • Ask user: "Frontend clone may be outdated. Pull latest changes?"
   • If yes: cd ../frontend && git pull
   • If no: Proceed with current state (user may want to compare against specific version)

The agent can ensure latest or ask for a git pull before comparisons.

Core Tasks

1. Verify File Locations

Check if files are in the correct location relative to upstream:

1. Extract GitHub URLs from file comments:

   /**
    * https://github.com/home-assistant/frontend/blob/dev/src/common/const.ts
    */
   

   → Expected local path: src/hass/common/const.ts → Upstream path: ../frontend/src/common/const.ts

2. Path mapping rule:

   • Upstream: ../frontend/src/[path]
   • Local: src/hass/[path]

3. Check for moved files:

   • If GitHub URL path doesn't match current file location → flag as moved
   • Verify if upstream file still exists at that path in local clone
   • Action: Move the file in this project to match upstream structure (not just update the URL)

2. Verify Code Matches Upstream

Ensure copied code matches upstream as closely as possible:

1. Read upstream content from local frontend clone:
   • Extract path from GitHub URL comment
   • Read file from ../frontend/src/[path]
2. Compare structure:
   • Export order (should match)
   • Function/class order (should match)
   • Import order (can differ if using local paths)
3. Identify intentional changes:
   • Look for comments like // MODIFIED: or // CHANGED:
   • Check if imports use @hass/ paths (local) vs original paths
4. Flag differences:
   • Reordered exports/functions
   • Missing code from upstream (unless intentional - e.g., partial types)
   • Extra code not in upstream
   • Code improvements without documentation comments

3. Identify Unused Code

Ensure unnecessary code isn't copied:

1. Check imports:
   • Search project for usage of imported symbols
   • Flag unused imports
2. Check exports:
   • Search project for usage of exported symbols
   • Flag unused exports (unless they're re-exported for convenience)
3. Check internal code:
   • Functions/types only used internally in hass folder
   • Verify they're actually needed by other hass files

Workflow

When syncing a file:

1. Ensure frontend clone is up to date (ask user or check git status)
2. Extract GitHub URL from comment
3. Map to local upstream path: ../frontend/src/[path]
4. Read upstream content from local clone
5. Compare:
   - [ ] File location matches expected path
   - [ ] Code structure matches (order, exports)
   - [ ] No unintentional changes
   - [ ] All imports/exports are used
6. Report findings

When checking all files:

1. Ensure frontend clone is up to date (ask user or check git status)
2. Scan all files in src/hass/
3. For each file:
   - Extract GitHub URL
   - Map to upstream path: ../frontend/src/[path]
   - Verify location
   - Check if upstream file exists in local clone
   - Read and compare content structure
   - Check usage
4. Generate report:
   - Files in wrong location
   - Files with mismatched content
   - Files with unused code
   - Files that may have moved upstream

GitHub URL Pattern

Files follow this pattern:

/**
 * https://github.com/home-assistant/frontend/blob/dev/src/[path]
 */

Path mapping:

• GitHub URL path: src/[path]
• Local file: src/hass/[path]
• Upstream file: ../frontend/src/[path]

The GitHub URL is kept for reference, but comparisons use the local frontend clone.

Intentional Modifications

Files may have intentional changes:

• Import paths changed to use @hass/ aliases
• Comments added with // MODIFIED: or // CHANGED:
• Partial code copied (only needed parts)
• Code improvements: Intentional improvements (e.g., SonarQube code smell cleanups) should be documented with comments explaining they are intentional
• Minimal types: Types/interfaces can be minimal or partial - only include fields that are actually used in this project

Always respect intentional modifications - only flag unintentional differences.

Usage Examples

Check a specific file:

Verify src/hass/data/entity.ts matches upstream

Check all files:

Audit all files in src/hass for sync issues

Find unused code:

Find unused imports/exports in src/hass

Verify file locations:

Check if any files need to be moved due to upstream changes