feat: home assistant integration

.github/workflows/ci.yml

@@ -30,6 +30,11 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
       - name: Setup uv and Python
         uses: astral-sh/setup-uv@v3
         with:
@@ -46,13 +51,25 @@ jobs:
       - name: Sync dependencies
         run: uv sync --group dev
 
+      - name: Install shellcheck
+        run: sudo apt-get update && sudo apt-get install -y shellcheck
+
+      - name: Shellcheck add-on scripts
+        run: make -C homeassistant shellcheck
+
       # Lint and typecheck run while Postgres boots
       - name: Lint
         run: make lint
 
+      - name: HA integration lint
+        run: make ha-lint
+
       - name: Type check
         run: make typecheck
 
+      - name: HA integration tests
+        run: make ha-test
+
       # Wait for Postgres before migrations
       - name: Wait for Postgres
         run: |

Makefile

@@ -1,7 +1,7 @@
 SHELL := /bin/bash
 .SHELLFLAGS := -eu -o pipefail -c
 
-.PHONY: help up down docker-build docker-push run db test coverage typecheck lint check db-migrate db-migration publish
+.PHONY: help up down docker-build docker-push run db test coverage typecheck lint check db-migrate db-migration publish ha-lint ha-test
 
 help:
 	@echo "Targets:"
@@ -20,6 +20,8 @@ help:
 	@echo "    make typecheck     Run mypy"
 	@echo "    make lint          Run ruff linter"
 	@echo "    make check         Run lint + typecheck + test"
+	@echo "    make ha-lint       Run ruff on HA integration code"
+	@echo "    make ha-test       Run HA integration tests"
 	@echo ""
 	@echo "  Database:"
 	@echo "    make db-migrate    Run migrations"
@@ -34,6 +36,9 @@ HOMESEC_LOG_LEVEL ?= INFO
 DOCKER_IMAGE ?= homesec
 DOCKER_TAG ?= latest
 DOCKERHUB_USER ?= $(shell echo $${DOCKERHUB_USER:-})
+HA_INTEGRATION_DIR := homeassistant/integration
+HA_INTEGRATION_SRC := $(HA_INTEGRATION_DIR)/custom_components
+HA_INTEGRATION_TESTS := $(HA_INTEGRATION_DIR)/tests
 
 # Docker
 up:
@@ -77,12 +82,21 @@ typecheck:
 lint:
 	uv run ruff check src tests
 	uv run ruff format --check src tests
+	make -C homeassistant shellcheck
+	make ha-lint
+
+ha-lint:
+	uv run ruff check $(HA_INTEGRATION_SRC) $(HA_INTEGRATION_TESTS)
+	uv run ruff format --check $(HA_INTEGRATION_SRC) $(HA_INTEGRATION_TESTS)
+
+ha-test:
+	uv run pytest $(HA_INTEGRATION_TESTS) -q
 
 lint-fix:
 	uv run ruff check --fix src tests
 	uv run ruff format src tests
 
-check: lint typecheck test
+check: lint typecheck test ha-lint ha-test
 
 # Database
 db-migrate:

config/example.yaml

@@ -111,6 +111,14 @@ notifiers:
       qos: 1
       retain: false
 
+  # Home Assistant Events API (recommended for HA users)
+  # - backend: home_assistant
+  #   config:
+  #     # When running as HA add-on, no configuration needed (uses SUPERVISOR_TOKEN)
+  #     # For standalone mode, provide HA URL and token:
+  #     # url_env: HA_URL           # http://homeassistant.local:8123
+  #     # token_env: HA_TOKEN       # Long-lived access token from HA
+
   # SendGrid email
   # - backend: sendgrid_email
   #   config:
@@ -196,8 +204,12 @@ alert_policy:
 #   filter_workers: 4
 #   vlm_workers: 2
 
-# Health check server
-# health:
+# FastAPI server
+# server:
+#   enabled: true
 #   host: "0.0.0.0"
 #   port: 8080
-#   mqtt_is_critical: false
+#   cors_origins:
+#     - "*"
+#   auth_enabled: false
+#   api_key_env: "HOMESEC_API_KEY"

docker-compose.yml

@@ -1,7 +1,7 @@
 services:
   homesec:
     build: .
-    image: leva/homesec:latest
+    image: leva/homesec:claude-homesec-home-assistant-integration-6kzkl
     pull_policy: always
     container_name: homesec
     restart: unless-stopped

docs/ha-phase-0-prerequisites.md

@@ -0,0 +1,7 @@
+# Phase 0: Core Prerequisites
+
+> **Note**: This phase has been merged into [Phase 1 (REST API)](./ha-phase-1-rest-api.md).
+>
+> The only prerequisite (`CameraConfig.enabled` field) is now part of Phase 1, section 1.1.1.
+
+See [Phase 1](./ha-phase-1-rest-api.md) for implementation details.