docs: add devices packs append-only policy (fixes #79) (#109)

* feat: devices export JSON snapshot CLI (#78)

* feat: add pip caching + pytest-cov to CI (#18)

* docs: add devices packs append-only policy (fixes #79)

---------

Co-authored-by: CloneBro <rundm.wiechmann@gmail.com>

Author: CloneBro

.github/workflows/ci.yml

@@ -19,13 +19,15 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: packages/bridge/pyproject.toml
       - name: Install
         run: |
           python -m pip install -U pip
           pip install -e ".[dev,api]"
       - name: Ruff
         run: ruff check src tests
       - name: Pytest
-        run: pytest -q
+        run: pytest -q --cov=hiri_bridge --cov-fail-under=60
       - name: Demo
         run: hiri-bridge demo

CONTRIBUTING.md

@@ -121,6 +121,13 @@ HIRI uses [MergeOS MRG bounties](docs/BOUNTY.md).
 | Large (major features) | 100 |
 | XL (end-to-end, platform) | 200 |
 
+## Device packs
+
+When creating device packs in `packages/bridge/data/packs/`, follow the **append-only policy**:
+
+> ⚠️ **Important**: Device packs must **append** to the registry, never replace `devices.json`.  
+> See [docs/devices-packs-policy.md](docs/devices-packs-policy.md) for the full policy.
+
 ## Code quality
 
 - **Python**: `ruff check`, type hints encouraged, pytest for tests

docs/devices-packs-policy.md

@@ -0,0 +1,47 @@
+# Device Packs Policy
+
+## Append-Only for Device Packs
+
+**Device packs** (in `packages/bridge/data/packs/`) must **append** to the device registry and **never replace** the entire `devices.json`.
+
+## Why Append-Only?
+
+- **Seed devices** live in `data/devices.json` as the canonical baseline
+- **Packs** add domain-specific device packs on top of the seed
+- Replacing the entire registry would **overwrite** seed devices and user-discovered devices
+- Appending preserves the merge chain: `seed → pack1 → pack2 → ...`
+
+## How It Works
+
+The `DeviceRegistry` class merges pack data into the existing registry:
+
+```python
+# In src/hiri_bridge/config.py
+registry = DeviceRegistry.load(registry_path)
+registry.merge_pack(pack_data)  # Appends, not replaces
+```
+
+## Creating a Device Pack
+
+1. Create your pack JSON in `packages/bridge/data/packs/<pack-name>.json`
+2. Devices in the pack are **merged** into the registry (keyed by `id`)
+3. The pack's devices are **appended** to the registry, never overwriting seed devices
+4. Run `hiri-bridge devices list` to verify pack devices are visible
+
+## Anti-Truncation Rule
+
+**Never** write a pack file that replaces `devices.json` entirely. The registry expects to be built incrementally:
+
+```
+seed devices.json → merged with pack1 → merged with pack2 → ...
+```
+
+If a pack replaces the file instead, seed devices and previously merged devices will be **lost**.
+
+## Verification
+
+After creating a pack, verify it doesn't truncate existing devices:
+
+```bash
+hiri-bridge devices list | wc -l   # Should show seed + pack devices
+```

packages/bridge/.coverage

@@ -17,7 +17,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-dev = ["pytest>=8.0", "ruff>=0.4", "httpx>=0.27"]
+dev = ["pytest>=8.0", "pytest-cov>=4.0", "ruff>=0.4", "httpx>=0.27"]
 api = ["fastapi>=0.110", "uvicorn>=0.27", "httpx>=0.27"]
 mqtt = ["paho-mqtt>=2.0"]
 

packages/bridge/pyproject.toml

@@ -213,6 +213,18 @@ def devices_sim_history(
     console.print_json(data={"id": device_id, "n": len(rows), "history": rows})
 
 
+@devices_app.command("export")
+def devices_export(
+    out: Path = typer.Option(..., "--out", "-o", help="Output JSON file path"),
+) -> None:
+    """Export device registry as a JSON snapshot (no tokens/secrets)."""
+    reg = _registry()
+    snapshot = [d.model_dump() for d in reg.list()]
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(json.dumps(snapshot, indent=2) + "\n", encoding="utf-8")
+    console.print(f"[green]Wrote[/green] {out} devices={len(snapshot)}")
+
+
 @ha_app.command("discovery")
 def ha_discovery(out: Path | None = typer.Option(None, "--out", "-o")) -> None:
     reg = _registry()

packages/bridge/src/hiri_bridge/cli.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+
+def test_devices_export_writes_json(tmp_path: Path) -> None:
+    """hiri-bridge devices export --out writes device registry snapshot."""
+    out = tmp_path / "snapshot.json"
+    result = subprocess.run(
+        [sys.executable, "-m", "hiri_bridge.cli", "devices", "export", "--out", str(out)],
+        capture_output=True,
+        text=True,
+    )
+    assert result.returncode == 0, f"stdout={result.stdout} stderr={result.stderr}"
+    assert out.exists(), f"Expected {out} to exist. stderr={result.stderr}"
+
+    data = json.loads(out.read_text(encoding="utf-8"))
+    assert isinstance(data, list), f"Expected list, got {type(data)}"
+    assert len(data) > 0, "Registry should contain seeded devices"
+
+    # Check structure of first device
+    d = data[0]
+    for field in ("id", "name", "domain", "manufacturer", "model", "area", "online", "state", "adapter"):
+        assert field in d, f"Device missing field: {field}"
+
+    # Verify no tokens/secrets leaked
+    text = out.read_text(encoding="utf-8").lower()
+    assert "token" not in text or "code" not in text, "Snapshot should not contain tokens/codes"
+
+    # Verify output mentions device count
+    assert "devices=" in result.stdout and str(len(data)) in result.stdout
+
+
+def test_devices_export_creates_parent_dirs(tmp_path: Path) -> None:
+    """export --out creates parent directories if they don't exist."""
+    out = tmp_path / "nested" / "deep" / "snapshot.json"
+    assert not out.parent.exists()
+    result = subprocess.run(
+        [sys.executable, "-m", "hiri_bridge.cli", "devices", "export", "--out", str(out)],
+        capture_output=True,
+        text=True,
+    )
+    assert result.returncode == 0, f"stdout={result.stdout} stderr={result.stderr}"
+    assert out.exists()
+
+
+def test_devices_export_requires_out_option() -> None:
+    """export command requires --out argument."""
+    result = subprocess.run(
+        [sys.executable, "-m", "hiri_bridge.cli", "devices", "export"],
+        capture_output=True,
+        text=True,
+    )
+    assert result.returncode != 0, "export without --out should fail"