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:

   bash

   cd ../frontend && git status
   

2. •

   Check if behind upstream:

   bash

   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:

   typescript

   /**
    * 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