Add Docker dev environment and charging binary sensor (#67)

## Summary

- Add `Dockerfile.dev` — a minimal Python 3.12 image that installs
`requirements-test.txt` (which pulls in Home Assistant via
`pytest-homeassistant-custom-component`)
- Document the Docker-based workflow in `README.md` (Local Development
section) and `CLAUDE.md` so all contributors run tests and lint inside
the container rather than on the host
- Add `PetTracerChargingBinarySensor` to `binary_sensor.py`, wire it
into `async_setup_entry`, and add full test coverage in
`tests/test_binary_sensor.py`

## Test plan

- [ ] `docker build -f Dockerfile.dev -t pettracer-dev .` completes
successfully
- [ ] `docker run --rm -v "$PWD":/workspace pettracer-dev pytest
--cov=custom_components.pettracer --cov-report=term -v` — all tests
pass, coverage ≥80%
- [ ] CI test and validate jobs pass

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: kylegordon

CLAUDE.md

@@ -0,0 +1,60 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+All development runs inside Docker — do not install dependencies directly on the host.
+
+Build the dev image (required once, and after `requirements-test.txt` changes):
+```bash
+docker build -f Dockerfile.dev -t pettracer-dev .
+```
+
+Run tests with coverage:
+```bash
+docker run --rm -v "$PWD":/workspace pettracer-dev \
+  pytest --cov=custom_components.pettracer --cov-report=term -v
+```
+
+Run a single test file:
+```bash
+docker run --rm -v "$PWD":/workspace pettracer-dev \
+  pytest tests/test_sensor.py -v
+```
+
+Lint and format:
+```bash
+docker run --rm -v "$PWD":/workspace pettracer-dev ruff check custom_components/pettracer/
+docker run --rm -v "$PWD":/workspace pettracer-dev ruff format custom_components/pettracer/
+```
+
+Validate JSON files after editing (CI blocks on invalid JSON):
+```bash
+docker run --rm -v "$PWD":/workspace pettracer-dev \
+  python -m json.tool custom_components/pettracer/manifest.json
+```
+
+Open an interactive shell in the container:
+```bash
+docker run --rm -it -v "$PWD":/workspace pettracer-dev bash
+```
+
+## Architecture
+
+This is a Home Assistant custom component that bridges the PetTracer GPS collar cloud API to HA entities. The external `pettracer-client` PyPI package handles all API communication.
+
+**Setup flow:** `config_flow.py` collects credentials → `__init__.py` authenticates and creates a `PetTracerDataUpdateCoordinator` → coordinator is stored in `hass.data[DOMAIN][entry_id]` → three platforms (`binary_sensor`, `device_tracker`, `sensor`) each pull the coordinator from `hass.data` and register entities per device.
+
+**Data flow:** The coordinator calls `client.get_all_devices()` every 60 seconds. Each platform's `async_setup_entry` iterates `coordinator.data["devices"]` and creates entities. Entities extend `CoordinatorEntity` and call `_get_device_data()` to look up their specific device by `device.id` from the coordinator's latest data.
+
+**Sensor pattern:** `sensor.py` uses `PetTracerSensorEntityDescription` (a frozen dataclass extending `SensorEntityDescription`) with a `value_fn: Callable[[device], Any]` field. Adding a new sensor means writing a `_get_*` function and adding an entry to `SENSOR_DESCRIPTIONS` — no new class needed.
+
+**Binary sensors:** `binary_sensor.py` has two concrete classes (`PetTracerAtHomeBinarySensor`, `PetTracerChargingBinarySensor`). These follow the same `CoordinatorEntity` + `_get_device_data()` pattern but are explicit classes rather than description-driven.
+
+## CI Behaviour
+
+- **Tests** (`pytest` job): must pass; enforces ≥80% coverage with `coverage report --fail-under=80`.
+- **Validate** job: blocks on invalid JSON in `manifest.json`, `strings.json`, `translations/en.json`, `hacs.json`.
+- **Lint** job: `continue-on-error: true` — linting failures do not block CI.
+- Changing the `version` field in `manifest.json` triggers the auto-release workflow (creates a GitHub release and HACS ZIP). Don't bump the version unless you intend a release.

Dockerfile.dev

@@ -0,0 +1,8 @@
+FROM python:3.12-slim
+
+WORKDIR /workspace
+
+COPY requirements-test.txt .
+RUN pip install --no-cache-dir -r requirements-test.txt
+
+COPY . .

README.md

@@ -261,6 +261,44 @@ This integration is built using:
 - Home Assistant integration framework
 - Config flow for easy setup
 
+### Local Development
+
+All development is done inside Docker to avoid polluting your host with dependencies.
+
+**Build the dev image** (once, and after `requirements-test.txt` changes):
+
+```bash
+docker build -f Dockerfile.dev -t pettracer-dev .
+```
+
+**Run the full test suite:**
+
+```bash
+docker run --rm -v "$PWD":/workspace pettracer-dev \
+  pytest --cov=custom_components.pettracer --cov-report=term -v
+```
+
+**Run a single test file:**
+
+```bash
+docker run --rm -v "$PWD":/workspace pettracer-dev pytest tests/test_sensor.py -v
+```
+
+**Lint / format:**
+
+```bash
+docker run --rm -v "$PWD":/workspace pettracer-dev ruff check custom_components/pettracer/
+docker run --rm -v "$PWD":/workspace pettracer-dev ruff format custom_components/pettracer/
+```
+
+**Interactive shell:**
+
+```bash
+docker run --rm -it -v "$PWD":/workspace pettracer-dev bash
+```
+
+The source tree is bind-mounted at `/workspace`, so code changes take effect immediately without rebuilding the image.
+
 ### File Structure
 
 ```

custom_components/pettracer/binary_sensor.py

@@ -24,9 +24,10 @@ async def async_setup_entry(
     """Set up PetTracer binary sensors based on a config entry."""
     coordinator = hass.data[DOMAIN][config_entry.entry_id]
 
-    entities: list[PetTracerAtHomeBinarySensor] = []
+    entities: list = []
     for device in coordinator.data.get("devices", []):
         entities.append(PetTracerAtHomeBinarySensor(coordinator, device))
+        entities.append(PetTracerChargingBinarySensor(coordinator, device))
 
     async_add_entities(entities, True)
 
@@ -72,3 +73,46 @@ def is_on(self) -> bool | None:
         if device and device.home is not None:
             return device.home
         return None
+
+
+class PetTracerChargingBinarySensor(CoordinatorEntity, BinarySensorEntity):
+    """Representation of a PetTracer charging binary sensor."""
+
+    _attr_device_class = BinarySensorDeviceClass.BATTERY_CHARGING
+
+    def __init__(self, coordinator, device):
+        """Initialize the binary sensor."""
+        super().__init__(coordinator)
+        self._device = device
+        self._device_id = device.id
+        self._device_name = (
+            device.details.name if device.details else f"PetTracer {device.id}"
+        )
+        self._attr_unique_id = f"pettracer_{device.id}_charging"
+        self._attr_name = f"{self._device_name} Charging"
+
+    @property
+    def device_info(self) -> dict[str, Any]:
+        """Return device information about this sensor."""
+        return {
+            "identifiers": {(DOMAIN, self._device_id)},
+            "name": self._device_name,
+            "manufacturer": "PetTracer",
+            "model": "GPS Collar",
+            "sw_version": self._device.sw if self._device.sw else None,
+        }
+
+    def _get_device_data(self):
+        """Get updated device data from coordinator."""
+        for device in self.coordinator.data.get("devices", []):
+            if device.id == self._device_id:
+                return device
+        return None
+
+    @property
+    def is_on(self) -> bool | None:
+        """Return true if the collar is charging."""
+        device = self._get_device_data()
+        if device and device.chg is not None:
+            return bool(device.chg)
+        return None

tests/conftest.py

@@ -62,6 +62,7 @@ def mock_device():
     device.status = 0
     device.mode = 1
     device.home = True
+    device.chg = 1
     device.sw = 656393
     device.lastContact = datetime(2026, 1, 11, 10, 30, 0)
 
@@ -90,6 +91,7 @@ def mock_device_no_position():
     device.status = 0
     device.mode = 1
     device.home = False
+    device.chg = 0
     device.sw = 656393
     device.lastContact = datetime(2026, 1, 11, 10, 0, 0)
 

tests/test_binary_sensor.py

@@ -9,7 +9,10 @@
 from homeassistant.components.binary_sensor import BinarySensorDeviceClass
 
 from custom_components.pettracer.const import DOMAIN
-from custom_components.pettracer.binary_sensor import PetTracerAtHomeBinarySensor
+from custom_components.pettracer.binary_sensor import (
+    PetTracerAtHomeBinarySensor,
+    PetTracerChargingBinarySensor,
+)
 
 
 async def test_binary_sensor_setup(hass, mock_pettracer_client_init, mock_device):
@@ -48,8 +51,9 @@ def mock_add_entities(new_entities, update_before_add):
 
         await binary_sensor_setup(hass, entry, mock_add_entities)
 
-        assert len(entities) == 1
+        assert len(entities) == 2
         assert isinstance(entities[0], PetTracerAtHomeBinarySensor)
+        assert isinstance(entities[1], PetTracerChargingBinarySensor)
 
 
 async def test_at_home_binary_sensor_true(hass, mock_device):
@@ -105,3 +109,58 @@ async def test_at_home_binary_sensor_device_info(hass, mock_device):
     assert device_info["name"] == "Fluffy"
     assert device_info["manufacturer"] == "PetTracer"
     assert device_info["model"] == "GPS Collar"
+
+
+async def test_charging_binary_sensor_true(hass, mock_device):
+    """Test charging binary sensor when collar is charging."""
+    coordinator = MagicMock()
+    coordinator.data = {"devices": [mock_device]}
+
+    sensor = PetTracerChargingBinarySensor(coordinator, mock_device)
+
+    assert sensor.unique_id == "pettracer_12345_charging"
+    assert sensor.name == "Fluffy Charging"
+    assert sensor.device_class == BinarySensorDeviceClass.BATTERY_CHARGING
+    assert sensor.is_on is True
+
+
+async def test_charging_binary_sensor_false(hass, mock_device_no_position):
+    """Test charging binary sensor when collar is not charging."""
+    coordinator = MagicMock()
+    coordinator.data = {"devices": [mock_device_no_position]}
+
+    sensor = PetTracerChargingBinarySensor(coordinator, mock_device_no_position)
+
+    assert sensor.unique_id == "pettracer_12346_charging"
+    assert sensor.name == "Rex Charging"
+    assert sensor.is_on is False
+
+
+async def test_charging_binary_sensor_none(hass):
+    """Test charging binary sensor when chg is None."""
+    device = MagicMock()
+    device.id = 99999
+    device.details = None
+    device.chg = None
+    device.sw = None
+
+    coordinator = MagicMock()
+    coordinator.data = {"devices": [device]}
+
+    sensor = PetTracerChargingBinarySensor(coordinator, device)
+
+    assert sensor.is_on is None
+
+
+async def test_charging_binary_sensor_device_info(hass, mock_device):
+    """Test charging binary sensor device info."""
+    coordinator = MagicMock()
+    coordinator.data = {"devices": [mock_device]}
+
+    sensor = PetTracerChargingBinarySensor(coordinator, mock_device)
+    device_info = sensor.device_info
+
+    assert device_info["identifiers"] == {(DOMAIN, 12345)}
+    assert device_info["name"] == "Fluffy"
+    assert device_info["manufacturer"] == "PetTracer"
+    assert device_info["model"] == "GPS Collar"