homesec 1.0.1__tar.gz → 1.1.0__tar.gz

{homesec-1.0.1 → homesec-1.1.0}/.github/workflows/ci.yml

@@ -5,6 +5,10 @@ on:
     branches: [main, master]
   pull_request:
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   ci:
     runs-on: ubuntu-latest
@@ -40,7 +44,7 @@ jobs:
           key: venv-${{ runner.os }}-py3.14-${{ hashFiles('uv.lock') }}
 
       - name: Sync dependencies
-        run: uv sync
+        run: uv sync --group dev
 
       # Lint and typecheck run while Postgres boots
       - name: Lint
@@ -61,5 +65,12 @@ jobs:
       - name: Run migrations
         run: uv run alembic -c alembic.ini upgrade head
 
-      - name: Test
-        run: make test
+      - name: Test with coverage
+        run: make coverage
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.xml
+          fail_ci_if_error: false

{homesec-1.0.1 → homesec-1.1.0}/AGENTS.md

@@ -1,6 +1,6 @@
 # HomeSec Development Guidelines
 
-**Last reviewed:** 2025-01-04
+**Last reviewed:** 2025-01-11
 **Purpose:** Critical patterns to prevent runtime bugs when extending HomeSec. For architecture overview, see `DESIGN.md`.
 
 ---
@@ -11,7 +11,7 @@
 - **Program to interfaces**: Use factory/registry helpers (e.g., `load_filter_plugin()`). Avoid direct instantiation of plugins.
 - **Repository pattern**: Use `ClipRepository` for all state/event writes. Never touch `StateStore`/`EventStore` directly.
 - **Preserve stack traces**: Custom errors must set `self.__cause__ = cause` to preserve original exception.
-- **Tests must use Given/When/Then comments**: Every test case must include these comments (new or edited).
+- **Tests must use Given/When/Then comments**: Every test must include these comments and follow behavioral testing principles (see `TESTING.md`).
 - **Postgres for state**: Use `clip_states` table with `clip_id` (primary key) + `data` (jsonb) for evolvable schema.
 - **Pydantic everywhere**: Validate config, DB payloads, VLM outputs, and MQTT payloads with Pydantic models.
 - **Clarify before complexity**: Ask user for clarification when simpler design may exist. Don't proceed with complex workarounds.
@@ -277,13 +277,20 @@ def register():
 
 ### 5. Testing Requirements
 
-**Rule:** All tests must use Given/When/Then comments. Use mocks from `tests/homesec/mocks/`.
+**Rule:** All tests must use Given/When/Then comments. Follow principles in `TESTING.md` for writing high-quality tests.
+
+**Key Principles (see `TESTING.md` for full details):**
+- **Test observable behavior, not internal state** - Never assert on `obj._private_attr`
+- **Mock at the boundary** - Mock HTTP/network, not internal methods
+- **Use contract testing** - Capture and verify API request structure
+- **Use real implementations where cheap** - Filesystem via `tmp_path`, pure functions
+- **Track API calls, not state flags** - Use `api_calls: list[str]` not `was_called: bool`
 
 **✅ Template: Test with Given/When/Then**
 
 ```python
 async def test_filter_stage_success():
-    # Given: A clip with person detected
+    # Given: A clip and a filter configured to detect person
     clip = Clip(clip_id="test-001", camera_name="front_door", ...)
     mock_filter = MockFilter(result=FilterResult(detected_classes=["person"], confidence=0.9))
     pipeline = ClipPipeline(filter_plugin=mock_filter, ...)
@@ -294,7 +301,7 @@ async def test_filter_stage_success():
     # Then: Should return FilterResult with detected person
     assert isinstance(result, FilterResult)
     assert "person" in result.detected_classes
-    assert mock_filter.detect_count == 1
+    assert result.confidence == 0.9
 
 async def test_filter_stage_failure():
     # Given: A filter that simulates failure
@@ -304,14 +311,14 @@ async def test_filter_stage_failure():
     # When: Processing clip through filter stage
     result = await pipeline._filter_stage(clip)
 
-    # Then: Should return FilterError with cause preserved
+    # Then: Should return FilterError (error-as-value pattern)
     assert isinstance(result, FilterError)
-    assert result.cause is not None
     assert result.clip_id == clip.clip_id
 ```
 
 **Available Mocks:** `MockFilter`, `MockVLM`, `MockStorage`, `MockNotifier`, `MockStateStore`, `MockEventStore`
-All mocks support `simulate_failure=True` and track call counts.
+
+**Reference:** See `TESTING.md` for comprehensive testing guidelines and anti-patterns to avoid.
 
 ---
 
@@ -404,6 +411,7 @@ token: "sl.ABC123..."  # Don't do this!
 
 **Architecture & Design:**
 - See `DESIGN.md` for full architecture overview and design decisions
+- See `TESTING.md` for comprehensive testing guidelines and principles
 - See `src/homesec/interfaces.py` for complete interface definitions
 
 **Plugin Development:**

homesec-1.1.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v1.1.0 (2026-01-12)
+
+### Bug Fixes
+
+- Add Codecov token to CI workflow ([#5](https://github.com/lan17/homesec/pull/5),
+  [`6657cf2`](https://github.com/lan17/homesec/commit/6657cf2e94fe7bf8d0eaed39cfa98242f9766188))
+
+- Correct Codecov badge URL case (HomeSec) ([#6](https://github.com/lan17/homesec/pull/6),
+  [`74019fe`](https://github.com/lan17/homesec/commit/74019fe4b313d588a72e96ff86a7b647e69c8150))
+
+### Features
+
+- Add code coverage and improve documentation ([#4](https://github.com/lan17/homesec/pull/4),
+  [`b1d9490`](https://github.com/lan17/homesec/commit/b1d949057db675ed20f2623f06cef1fd58c4dcc3))
+
+### Testing
+
+- Improve code coverage from 64% to 70% ([#7](https://github.com/lan17/homesec/pull/7),
+  [`7b93468`](https://github.com/lan17/homesec/commit/7b934685e8389bb24c8cc8878cb43b5570f5371e))
+
+
+## v1.0.2 (2026-01-11)
+
+### Bug Fixes
+
+- CI and release workflow improvements ([#3](https://github.com/lan17/homesec/pull/3),
+  [`ab61e47`](https://github.com/lan17/homesec/commit/ab61e47c7c16c79e8472807c07e4974e31a13c29))
+
+
+## v1.0.1 (2026-01-11)
+
+### Bug Fixes
+
+- Improve release workflow dry run and prevent major version jumps
+  ([#2](https://github.com/lan17/HomeSec/pull/2),
+  [`ba02512`](https://github.com/lan17/HomeSec/commit/ba025129de5caa984552807e4e0f376666db485e))
+
+
+## v1.0.0 (2026-01-11)
+
+- Initial Release

{homesec-1.0.1 → homesec-1.1.0}/Makefile

@@ -1,7 +1,7 @@
 SHELL := /bin/bash
 .SHELLFLAGS := -eu -o pipefail -c
 
-.PHONY: help up down docker-build docker-push run db test 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
 
 help:
 	@echo "Targets:"
@@ -15,7 +15,8 @@ help:
 	@echo "  Local dev:"
 	@echo "    make run           Run HomeSec locally (requires Postgres)"
 	@echo "    make db            Start just Postgres"
-	@echo "    make test          Run tests"
+	@echo "    make test          Run tests with coverage"
+	@echo "    make coverage      Run tests and generate HTML coverage report"
 	@echo "    make typecheck     Run mypy"
 	@echo "    make lint          Run ruff linter"
 	@echo "    make check         Run lint + typecheck + test"
@@ -64,7 +65,11 @@ db:
 	docker compose up -d postgres
 
 test:
-	uv run pytest tests/homesec/ -v
+	uv run pytest tests/homesec/ -v --cov=homesec --cov-report=term-missing
+
+coverage:
+	uv run pytest tests/homesec/ -v --cov=homesec --cov-report=html --cov-report=xml
+	@echo "Coverage report: htmlcov/index.html"
 
 typecheck:
 	uv run mypy --package homesec --strict

{homesec-1.0.1 → homesec-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: homesec
-Version: 1.0.1
+Version: 1.1.0
 Summary: Pluggable async home security camera pipeline with detection, VLM analysis, and alerts.
 Project-URL: Homepage, https://github.com/lan17/homesec
 Project-URL: Source, https://github.com/lan17/homesec
@@ -246,15 +246,31 @@ Description-Content-Type: text/markdown
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![Python: 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
 [![Typing: Typed](https://img.shields.io/badge/typing-typed-2b825b)](https://peps.python.org/pep-0561/)
+[![codecov](https://codecov.io/gh/lan17/HomeSec/branch/main/graph/badge.svg)](https://codecov.io/gh/lan17/HomeSec)
 
 HomeSec is a self-hosted, extensible network video recorder that puts you in control. Store clips wherever you want, analyze them with AI, and get smart notifications—all while keeping your footage private and off third-party clouds.
 
-Under the hood, it's a pluggable async pipeline for home security cameras. It records short clips, runs object detection, optionally calls a vision-language model (VLM) for a structured summary, and sends alerts via MQTT or email. The design leans toward reliability: clips land on disk first, state/event writes are best-effort, and non-critical stages can fail without losing the alert.
+Under the hood, it's a pluggable async pipeline for home security cameras. It records short clips, runs object detection, optionally calls a vision-language model ([VLM](https://en.wikipedia.org/wiki/Vision%E2%80%93language_model)) for a structured summary, and sends alerts via [MQTT](https://en.wikipedia.org/wiki/MQTT) or email. The design prioritizes reliability and extensibility.
+
+## Table of Contents
+
+- [Highlights](#highlights)
+- [Pipeline at a glance](#pipeline-at-a-glance)
+- [Quickstart](#quickstart)
+- [Configuration](#configuration)
+- [Extensible by design](#extensible-by-design)
+- [CLI](#cli)
+- [Built-in plugins](#built-in-plugins)
+- [Writing a plugin](#writing-a-plugin)
+- [Observability](#observability)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Highlights
 
-- Bring your own input: RTSP motion detection, FTP uploads, or a watched folder
-- Parallel upload + filter (YOLOv8) with frame sampling and early exit
+- Multiple pluggable video clip sources: [RTSP](https://en.wikipedia.org/wiki/Real-Time_Streaming_Protocol) motion detection, [FTP](https://en.wikipedia.org/wiki/File_Transfer_Protocol) uploads, or a watched folder
+- Parallel upload + filter ([YOLOv8](https://en.wikipedia.org/wiki/You_Only_Look_Once)) with frame sampling and early exit
 - OpenAI-compatible VLM analysis with structured output
 - Policy-driven alerts with per-camera overrides
 - Fan-out notifiers (MQTT for Home Assistant, SendGrid email)
@@ -276,6 +292,7 @@ ClipSource -> (Upload + Filter) -> VLM (optional) -> Alert Policy -> Notifier(s)
 
 ### Requirements
 
+- Raspberry Pi 4 (or equivalent) or higher; any x86_64 system works as well
 - Docker and Docker Compose
 - Optional: MQTT broker, Dropbox credentials, OpenAI-compatible API key
 
@@ -476,6 +493,30 @@ my_filters = "my_package.filters.custom"
 - Tests must include Given/When/Then comments.
 - Architecture notes: `DESIGN.md`
 
+## Contributing
+
+Contributions are welcome! Here's how to get started:
+
+1. **Fork and clone** the repository
+2. **Create a branch** for your feature or fix: `git checkout -b my-feature`
+3. **Install dependencies**: `uv sync`
+4. **Make your changes** and ensure tests pass: `make check`
+5. **Submit a pull request** with a clear description of your changes
+
+### Guidelines
+
+- All code must pass CI checks: `make check`
+- Tests should include Given/When/Then comments explaining the test scenario
+- New plugins should follow the existing patterns in `src/homesec/plugins/`
+- Keep PRs focused on a single change for easier review
+
+### Reporting Issues
+
+Found a bug or have a feature request? Please [open an issue](../../issues) with:
+- A clear description of the problem or suggestion
+- Steps to reproduce (for bugs)
+- Your environment (OS, Python version, HomeSec version)
+
 ## License
 
 Apache 2.0. See `LICENSE`.

{homesec-1.0.1 → homesec-1.1.0}/README.md

@@ -3,15 +3,31 @@
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![Python: 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
 [![Typing: Typed](https://img.shields.io/badge/typing-typed-2b825b)](https://peps.python.org/pep-0561/)
+[![codecov](https://codecov.io/gh/lan17/HomeSec/branch/main/graph/badge.svg)](https://codecov.io/gh/lan17/HomeSec)
 
 HomeSec is a self-hosted, extensible network video recorder that puts you in control. Store clips wherever you want, analyze them with AI, and get smart notifications—all while keeping your footage private and off third-party clouds.
 
-Under the hood, it's a pluggable async pipeline for home security cameras. It records short clips, runs object detection, optionally calls a vision-language model (VLM) for a structured summary, and sends alerts via MQTT or email. The design leans toward reliability: clips land on disk first, state/event writes are best-effort, and non-critical stages can fail without losing the alert.
+Under the hood, it's a pluggable async pipeline for home security cameras. It records short clips, runs object detection, optionally calls a vision-language model ([VLM](https://en.wikipedia.org/wiki/Vision%E2%80%93language_model)) for a structured summary, and sends alerts via [MQTT](https://en.wikipedia.org/wiki/MQTT) or email. The design prioritizes reliability and extensibility.
+
+## Table of Contents
+
+- [Highlights](#highlights)
+- [Pipeline at a glance](#pipeline-at-a-glance)
+- [Quickstart](#quickstart)
+- [Configuration](#configuration)
+- [Extensible by design](#extensible-by-design)
+- [CLI](#cli)
+- [Built-in plugins](#built-in-plugins)
+- [Writing a plugin](#writing-a-plugin)
+- [Observability](#observability)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Highlights
 
-- Bring your own input: RTSP motion detection, FTP uploads, or a watched folder
-- Parallel upload + filter (YOLOv8) with frame sampling and early exit
+- Multiple pluggable video clip sources: [RTSP](https://en.wikipedia.org/wiki/Real-Time_Streaming_Protocol) motion detection, [FTP](https://en.wikipedia.org/wiki/File_Transfer_Protocol) uploads, or a watched folder
+- Parallel upload + filter ([YOLOv8](https://en.wikipedia.org/wiki/You_Only_Look_Once)) with frame sampling and early exit
 - OpenAI-compatible VLM analysis with structured output
 - Policy-driven alerts with per-camera overrides
 - Fan-out notifiers (MQTT for Home Assistant, SendGrid email)
@@ -33,6 +49,7 @@ ClipSource -> (Upload + Filter) -> VLM (optional) -> Alert Policy -> Notifier(s)
 
 ### Requirements
 
+- Raspberry Pi 4 (or equivalent) or higher; any x86_64 system works as well
 - Docker and Docker Compose
 - Optional: MQTT broker, Dropbox credentials, OpenAI-compatible API key
 
@@ -233,6 +250,30 @@ my_filters = "my_package.filters.custom"
 - Tests must include Given/When/Then comments.
 - Architecture notes: `DESIGN.md`
 
+## Contributing
+
+Contributions are welcome! Here's how to get started:
+
+1. **Fork and clone** the repository
+2. **Create a branch** for your feature or fix: `git checkout -b my-feature`
+3. **Install dependencies**: `uv sync`
+4. **Make your changes** and ensure tests pass: `make check`
+5. **Submit a pull request** with a clear description of your changes
+
+### Guidelines
+
+- All code must pass CI checks: `make check`
+- Tests should include Given/When/Then comments explaining the test scenario
+- New plugins should follow the existing patterns in `src/homesec/plugins/`
+- Keep PRs focused on a single change for easier review
+
+### Reporting Issues
+
+Found a bug or have a feature request? Please [open an issue](../../issues) with:
+- A clear description of the problem or suggestion
+- Steps to reproduce (for bugs)
+- Your environment (OS, Python version, HomeSec version)
+
 ## License
 
 Apache 2.0. See `LICENSE`.