5b9111afa7
ken is HAOS (no SSH/docker exec path), so it needs a REST/WebSocket-only adapter: automations/scripts/scenes via one GET per /api/config/<domain>/config/<id>, dashboards/area+entity registries/ input_* helpers via the HA WebSocket API (read-only commands only). scripts/ha/lib/ha_api.py and ha_ws.py never take a token as a value — only a token_path, read from disk in-process — so the bearer token never touches a subprocess argv or a log line. ha_ws.py depends on the optional websocket-client package and raises a clear, actionable ImportError if it's missing rather than a raw traceback; import.sh still completes the REST-only part of the import in that case. Automations/scripts/scenes reuse split.write_split() so both adapters produce byte-identical config/<instance>/ layouts and the same idempotent stale-file cleanup on re-run. docker-exec adapter logic is untouched.
4.4 KiB
home-assistant (configs-as-code)
Status: skeleton. Structure and read-only import tooling only — no
deploy path exists yet. See DESIGN.md for the full phasing, adapter, sync,
and validation model, and for the open questions still blocking phase 2/3.
Layout
services/home-assistant/
├── DESIGN.md # decision registry — read this first
├── instances.yaml # per-instance adapter/host/token config
├── .gitignore # excludes secrets/db/log/token paths from every import
├── config/<instance>/ # canonical, normalized /config mirror per instance
├── storage-export/<instance>/ # curated .storage/* export (registries, dashboards)
└── fixtures/ # dated /api/states snapshots
Instances: ken (RPi4/HAOS, LAN 192.168.31.7, api adapter — canonical home
instance since the 2026-07-22 cutover), ken-legacy (PIHA, container
homeassistant5, docker-exec adapter, archived — pre-migration instance,
import only, never deploy), chelsty-ha (Tailscale, api adapter — see
instances.yaml and DESIGN.md "Incident log").
Import
scripts/ha/import.sh ken
scripts/ha/import.sh ken-legacy
Read-only, and idempotent for both adapters — re-running against an unchanged instance produces no diff.
docker-exec adapter (ken-legacy): pulls the whole /config tree
over ssh ... docker exec ... tar, filters it through .gitignore,
normalizes and splits it into config/<instance>/, exports curated
.storage/* into storage-export/<instance>/.
api adapter (ken, chelsty-ha): for instances with no
filesystem/SSH access (HAOS has none). Pulls automations/scripts/scenes via
one REST GET per object (/api/config/<domain>/config/<id>) and
dashboards/area+entity registries/input_* helpers via the WebSocket API
(/api/websocket) — read-only commands only, nothing that mutates the live
instance. Full /config import is out of scope for this adapter; see
DESIGN.md, "Deploy path: adapter per instance".
Both adapters also write a dated /api/states fixture snapshot to
fixtures/ if a deploy token exists at
~/.config/ha-deploy/<instance>.token. For the api adapter, that token is
not optional — see "Tokens" below.
Tokens
The api adapter has no filesystem fallback, so a missing or empty token
at token_path (see instances.yaml) is a hard error, not a soft-skip —
import.sh aborts immediately with a clear message rather than silently
producing an empty import. See DESIGN.md, "Tokens", for how the
deploy_agent account and its long-lived access token are provisioned.
The token itself never touches a subprocess argv or a log line: REST calls
go through scripts/ha/lib/ha_api.py, which reads the token file itself and
sets the Authorization header in-process via requests (never curl -H,
which would put the token in that process's argv, visible to any local user
via ps). requests (python3-requests) is a very common preinstalled/
transitive package on Debian-based nodes; if it's ever missing, import.sh
fails with Python's own ModuleNotFoundError — install it the same way as
python3-websocket below (sudo apt install python3-requests or pip install --user requests).
WebSocket dependency
The dashboard/registry/helper export (scripts/ha/lib/ha_ws.py) depends on
the websocket-client PyPI package (import name websocket) — not in the
stdlib, not installed by default. Install one of:
sudo apt install python3-websocket # Debian/Ubuntu package name
# or
pip install --user websocket-client
If it's missing, import.sh ken still imports automations/scripts/scenes
(REST-only, no extra dependency needed) and then reports the
dashboards/registries/helpers step as skipped with an actionable message
naming the package to install — it does not crash with a raw traceback, and
it does not silently produce an incomplete storage-export/ without saying
so.
Tests
scripts/ha/tests/test_split_normalize.sh
scripts/ha/tests/test_normalize_tags.sh
scripts/ha/tests/test_import_api_offline.sh
All offline — no network, no HA instance required. test_import_api_offline.sh
covers the api adapter: normalization of real-shaped API responses (saved
as fixtures under tests/fixtures/), idempotency, stale-file cleanup, and
the missing-websocket-client error path (via sys.modules injection, not
an actual network call).