hadsync 0.2.2__tar.gz

hadsync-0.2.2/.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python3 -c ' *)",
+      "Bash(HA_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI1MWNjNTg4MzY0NzA0ODk0YThjOWMwMDg2ZGEwYTc2MCIsImlhdCI6MTc3ODE3NjgyNiwiZXhwIjoyMDkzNTM2ODI2fQ.BFWPnJp6Zxm0TIw5kGn2hImfEk51LOHnqQ_Zm5Dr09I hadsync init)",
+      "Bash(HA_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI1MWNjNTg4MzY0NzA0ODk0YThjOWMwMDg2ZGEwYTc2MCIsImlhdCI6MTc3ODE3NjgyNiwiZXhwIjoyMDkzNTM2ODI2fQ.BFWPnJp6Zxm0TIw5kGn2hImfEk51LOHnqQ_Zm5Dr09I hadsync config *)",
+      "Bash(python3 -c \"import websockets; print\\(dir\\(websockets\\)\\)\")",
+      "Bash(git init *)",
+      "Bash(HA_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI1MWNjNTg4MzY0NzA0ODk0YThjOWMwMDg2ZGEwYTc2MCIsImlhdCI6MTc3ODE3NjgyNiwiZXhwIjoyMDkzNTM2ODI2fQ.BFWPnJp6Zxm0TIw5kGn2hImfEk51LOHnqQ_Zm5Dr09I hadsync *)",
+      "Read(//Users/ggevorgyan/git/esp32/esp-tool/**)"
+    ]
+  }
+}

hadsync-0.2.2/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+---
+name: Bug report
+about: Something isn't working as expected
+labels: bug
+---
+
+**hadsync version**
+<!-- run: hadsync --version -->
+
+**Home Assistant version**
+<!-- run: hadsync list (shows HA version on connect), or check HA → Settings → About -->
+
+**Command that failed**
+```
+hadsync ...
+```
+
+**What happened**
+<!-- Clear description of the bug -->
+
+**Steps to reproduce**
+1.
+2.
+3.
+
+**Expected behaviour**
+
+**Actual behaviour / error output**
+```
+paste output here
+```
+
+**Additional context**
+<!-- Dashboard type (storage-mode vs strategy), network setup, etc. -->

hadsync-0.2.2/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest an improvement or new command
+labels: enhancement
+---
+
+**What problem does this solve?**
+<!-- Describe the workflow gap or pain point -->
+
+**Proposed solution**
+<!-- How you'd like it to work. CLI examples are helpful. -->
+
+**Alternatives considered**
+<!-- Other approaches you've thought of -->
+
+**Additional context**
+<!-- Screenshots, HA version, dashboard structure, etc. -->

hadsync-0.2.2/.gitignore

@@ -0,0 +1,32 @@
+# Python
+.venv/
+uv.lock
+.python-version
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+
+# hadsync runtime files
+.hadsync-state.json
+.ha-entities.json
+
+# dashboard workspace — lives in its own repo
+ha-dashboards/
+
+# VS Code extension build artifacts
+vscode-hadsync/out/
+vscode-hadsync/node_modules/
+vscode-hadsync/*.vsix

hadsync-0.2.2/.hadsync.yaml

@@ -0,0 +1,12 @@
+ha_url: http://192.168.68.103:8123
+ha_token: ${HA_TOKEN}
+workspace: /Users/ggevorgyan/git/esp32/esphome/home-assistant-dashboards
+pull:
+  refresh_entities: true
+  dashboards: all
+push:
+  require_validation: true
+  confirm: true
+validation:
+  warn_on_unknown_entities: true
+  entity_cache_max_age_days: 7

hadsync-0.2.2/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+## [v0.2.2] — 2026-05-10
+
+### Fixed — VS Code Extension
+
+- **Stale diagnostics after external pull** — Problems panel no longer retains old errors after `hadsync pull` is run from the terminal. A `FileSystemWatcher` on `**/lovelace.yaml` now re-validates automatically when any file changes on disk, regardless of whether the change came from VS Code or an external process.
+- **Incorrect "N modified" in status bar** — The status bar was counting every dashboard that had never been pushed as "modified", showing e.g. `13 modified` immediately after a clean pull. Fixed to use the same mtime-vs-last_pull comparison as `hadsync status` in the CLI — "modified" now means the local file was actually edited since the last pull.
+
+[v0.2.2]: https://github.com/gevgev/hadsync/releases/tag/v0.2.2
+
+---
+
+## [v0.2.1] — 2026-05-10
+
+### Added — Phase 1b (Conflict Detection)
+
+- **`hadsync diff` conflict detection** — stores a hash of the HA config at every pull; diff now classifies each divergence into one of four verdicts:
+  - **CONFLICT** — both local and HA changed since last pull (shown in red with explicit next-step options)
+  - **HA changed only** — warns and suggests `hadsync pull <id>`
+  - **Local changed only** — warns and suggests `hadsync push <id>`
+  - **No baseline** — generic message when dashboard was never pulled with the new hash tracking
+- **Pull timestamp in diff output** — `Last pull: 2026-05-10 18:19  (2h ago)` shown for each dashboard
+- **Annotated change summary** — HA and local card counts now show `← changed since pull` or `(unchanged since pull)` tags
+- **`ha_config_hash`** field in `.hadsync-state.json` — 16-char SHA-256 prefix of the normalized HA config stored on every pull; enables HA-side change detection without keeping a full config snapshot
+
+### Fixed
+
+- **Error handling gaps (community review)** — VS Code extension now shows `showErrorMessage()` popups on command failure; detects `hadsync not found` at activation with an Open Settings link; `onDidSaveTextDocument` wrapped in try/catch; 60-second subprocess timeout prevents VS Code freeze
+- **Python error messages** — `ha_ws.py` now distinguishes connection refused, DNS failure, timeout, and auth_invalid with targeted, actionable messages including next-step hints (e.g. where to generate a long-lived token in HA)
+- **Watch mode resilience** — `watcher.py` event handler wrapped in try/catch so an unexpected crash no longer silently kills the watchdog observer thread
+
+[v0.2.1]: https://github.com/gevgev/hadsync/releases/tag/v0.2.1
+
+---
+
+## [v0.2.0] — 2026-05-09
+
+Phases 2, 3, and 4 complete. All four design phases are now implemented.
+
+### Added — Phase 2 (Entity Validation)
+
+- **`hadsync entities refresh`** — fetches all entity states from HA `/api/states` and writes `.ha-entities.json`
+- **`hadsync entities list [filter]`** — lists cached entities with domain and friendly name, filtered by substring
+- **Entity ID extraction** — recursive walk of any Lovelace config depth; handles `entity:`, `entities:` (strings and dicts), conditional conditions, stack nesting, picture-elements, and any other nesting pattern
+- **Phase 2 validation** — unknown entity IDs reported with line numbers; silently skipped if cache is absent (no friction before first `entities refresh`)
+- **Cache age warning** — warns when entity cache exceeds `validation.entity_cache_max_age_days` (default: 7)
+- **`validation.warn_on_unknown_entities`** config flag — controls whether unknown IDs are warnings (default) or errors that block push
+
+### Added — Phase 3 (Schema Validation & Watch)
+
+- **`hadsync watch [ID] [--auto-push]`** — watches workspace for `lovelace.yaml` saves; runs Phase 1+2+3 validation on every change; pushes to HA automatically when validation passes if `--auto-push` is set
+- **Phase 3 card schema validation** — 35 standard Lovelace card types with required-field checks; `custom:*` always passes; unknown non-custom types warn rather than block; extra prefixes configurable via `validation.custom_card_types`
+- **Enhanced `hadsync diff`** — view-by-view change summary (`+ added`, `- removed`, `~ N cards changed`) shown before the optional unified diff
+- **`validation.custom_card_types`** config field — list of additional type prefixes treated as valid alongside `custom:*`
+
+### Added — Phase 4 (VS Code Extension)
+
+- **`vscode-hadsync/`** — VS Code extension written in TypeScript; activates on any workspace containing `.hadsync.yaml`
+- **11 palette commands** (`Cmd+Shift+P`): pull (all / active), push (all / active, with confirmation dialog), validate (all / active), diff, status, list, entities refresh, entities search
+- **Inline diagnostics** — on `lovelace.yaml` save, runs `hadsync --json-output validate`; errors and warnings appear in the Problems panel and as editor squiggles with correct line numbers
+- **Status bar** — bottom-left item shows last pull time or modified-dashboard count; reads `.hadsync-state.json` directly; click opens status table
+- **Entity ID autocomplete** — completion items from `.ha-entities.json` triggered by `entity: ` and list item patterns; includes friendly name and domain in detail
+- **Context menu** — validate / push / diff available on right-click in any `lovelace.yaml` editor
+- **Settings**: `hadsync.executablePath`, `hadsync.validateOnSave` (default: true), `hadsync.autoPushOnSave` (default: false)
+
+### Changed
+
+- **`hadsync validate --json-output`** — emits structured JSON (per-dashboard file path, passed flag, issue list with severity/message/line); used by the VS Code extension for diagnostics; human output unchanged when flag is absent
+- **Validation pipeline** — `hadsync validate` and `hadsync push` pre-push validation now run Phase 1 + Phase 2 + Phase 3 in sequence
+- **`hadsync diff`** — now includes view-level summary before optional unified diff
+
+### Notes
+
+- Tested against **Home Assistant 2026.5.0**
+- VS Code extension requires `hadsync` on PATH or `hadsync.executablePath` setting; `HA_TOKEN` must be in the environment VS Code inherits
+
+---
+
+## [v0.1.0] — 2026-05-08
+
+Initial release. Phase 1 (Core CLI) complete.
+
+### Added
+
+- **`hadsync init`** — interactive setup: HA URL, token env var (with validation to catch pasted token values), workspace directory. Tests live HA connection.
+- **`hadsync list`** — discovers all storage-mode Lovelace dashboards on the HA instance.
+- **`hadsync pull [ID]`** — downloads one or all dashboards from HA as local YAML; auto-refreshes entity cache (`.ha-entities.json`); skips strategy-based dashboards with a warning.
+- **`hadsync push [ID]`** — uploads local YAML to HA with layered safety: pre-push validation, no-op guard (skips if already in sync), change summary (view/card counts), destructive-change warnings, explicit per-dashboard confirmation, and `--dry-run` mode.
+- **`hadsync validate [ID]`** — standalone YAML validation (syntax + structure) with PASS / WARN / FAIL per dashboard and line numbers on errors. Safe for CI pipelines — no HA connection required.
+- **`hadsync status`** — sync status table: last pull time, last push time, local state (clean / modified / never pulled). No HA connection required.
+- **`hadsync diff [ID] [--show]`** — compares local YAML against live HA state. `--show` renders a coloured unified diff (red = HA, green = local).
+- **`hadsync config show`** — displays resolved config with masked token and workspace source.
+- **`HADSYNC_WORKSPACE` env var** — overrides the workspace directory at runtime without editing config.
+
+### Notes
+
+- Tested against **Home Assistant 2026.5.0**.
+- The HA WebSocket commands referenced in common documentation (`lovelace/dashboards`, `lovelace/save_config`) do not exist in HA 2026.5. This release uses the correct equivalents: `get_panels` (filtered by `component_name=lovelace`) and `lovelace/config/save`.
+- Strategy-based dashboards (auto-generated by HA, e.g. the default Overview using `original-states` strategy) are detected during pull and skipped — they cannot be meaningfully round-tripped as static YAML.
+
+[v0.2.0]: https://github.com/gevgev/hadsync/releases/tag/v0.2.0
+[v0.1.0]: https://github.com/gevgev/hadsync/releases/tag/v0.1.0

hadsync-0.2.2/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing to hadsync
+
+Contributions are welcome — bug reports, feature requests, and pull requests.
+
+## Before you open a PR
+
+- Check [open issues](https://github.com/gevgev/hadsync/issues) to avoid duplicate work
+- For anything beyond a small fix, open an issue first to discuss the approach
+
+## Development setup
+
+```bash
+git clone https://github.com/gevgev/hadsync.git
+cd hadsync
+uv tool install --editable .   # or: pip install -e ".[dev]"
+pytest tests/
+```
+
+## Running tests
+
+```bash
+pytest tests/          # 43 unit tests, no HA connection required
+pytest tests/unit/     # unit tests only
+```
+
+Unit tests use no live HA instance. If you change `ha_ws.py`, please also test manually against a real HA instance — the WebSocket API has version-specific behavior that mocks cannot fully capture.
+
+## HA version compatibility
+
+hadsync is tested against **Home Assistant 2026.5**. Please note the HA version you tested against in your PR description.
+
+> **Note:** The WS commands used differ from common documentation. See [HA API Notes](README.md#ha-api-notes) in the README before touching the WebSocket client.
+
+## Code style
+
+- Python 3.11+, type annotations throughout
+- No comments describing *what* the code does — only *why* when non-obvious
+- Keep modules focused: CLI routing lives in `cli.py`, HA communication in `ha_ws.py` / `ha_rest.py`, etc.
+
+## Reporting bugs
+
+Please use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include your HA version — it matters for reproducing WS API issues.

hadsync-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gevorg Gevorgyan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.