franklinwh-modbus-async 0.0.1__tar.gz

franklinwh_modbus_async-0.0.1/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+site/
+
+# Local-only: never commit
+.env
+.pii-denylist
+captures/raw/
+tests/results/
+.DS_Store

franklinwh_modbus_async-0.0.1/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project are recorded here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+
+- **Phase 0 scaffold:**
+  - Packaging: Python >= 3.12, pinned `modbus-connection[tmodbus]~=4.12.4`.
+  - Code checks: ruff, mypy `--strict`, pytest-asyncio.
+  - CI on Python 3.12 and 3.13.
+- **PII guard** (`tools/pii_check.py`). It runs in pre-commit and CI and blocks:
+  - home-directory paths
+  - aGate serial numbers
+  - MAC addresses
+  - non-documentation IP addresses
+  - email addresses
+  - terms from a local `.pii-denylist` file
+- **Documentation:**
+  - `docs/why.md`: the library's purpose, basis and rationale, with a comparison table.
+  - `docs/research/modbus-connection.md`: findings on the transport.
+  - `PLAN.md`
+- **Release workflow** (`.github/workflows/release.yml`):
+  - Publishes to PyPI with trusted publishing (OIDC) when a `v*` tag is pushed.
+  - The PII guard runs before the build.
+- **sdist contents:** the source distribution includes only `src/`, `tests/`, the PII tool, README, LICENSE and CHANGELOG.

franklinwh_modbus_async-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 david2069
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

franklinwh_modbus_async-0.0.1/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: franklinwh-modbus-async
+Version: 0.0.1
+Summary: Async FranklinWH aGate Modbus TCP library (SunSpec + extension registers) built on modbus-connection
+Project-URL: Homepage, https://github.com/david2069/franklinwh-modbus-async
+Project-URL: Bug Tracker, https://github.com/david2069/franklinwh-modbus-async/issues
+Project-URL: Changelog, https://github.com/david2069/franklinwh-modbus-async/blob/main/CHANGELOG.md
+Author-email: david2069 <david2069@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agate,asyncio,battery,energy,franklinwh,modbus,sunspec
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Topic :: System :: Hardware
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: modbus-connection[tmodbus]~=4.12.4
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
+Provides-Extra: pymodbus
+Requires-Dist: modbus-connection[pymodbus]~=4.12.4; extra == 'pymodbus'
+Description-Content-Type: text/markdown
+
+# franklinwh-modbus-async
+
+An **async** Python library for the FranklinWH **aGate**. It talks Modbus TCP and covers the SunSpec models and the vendor extension registers. It is built on [`modbus-connection`](https://github.com/home-assistant-libs/modbus-connection).
+
+This is the asyncio successor to [`franklinwh-modbus`](https://github.com/david2069/franklinwh-modbus), which is synchronous. It aims to match that library's features and to fix its known connection and threading defects. To find out why it exists and how it compares, read **[docs/why.md](https://github.com/david2069/franklinwh-modbus-async/blob/main/docs/why.md)**.
+
+> **Status: pre-alpha (Phase 0 of 7).** The tooling and docs are in place, but there is no device API yet. See [PLAN.md](https://github.com/david2069/franklinwh-modbus-async/blob/main/PLAN.md) for the roadmap.
+
+> ## ⚠️ Unofficial software
+>
+> **About this software**
+>
+> - Not affiliated with, endorsed or supported by FranklinWH. FranklinWH and aGate are trademarks of their owners.
+> - Provided **as is**, without warranty, for educational and informational use.
+>
+> **Write commands carry real risk**
+>
+> - This library can send **write commands to grid-connected battery hardware**.
+> - Used incorrectly, it can discharge your battery when you need it, import power you did not intend to, or leave the system in an unexpected state.
+> - You use it at your own risk.
+>
+> **Getting help**
+>
+> - Do not contact FranklinWH support about this library. Report problems [here](https://github.com/david2069/franklinwh-modbus-async/issues).
+
+## Requirements
+
+- An aGate with **Modbus TCP enabled** (ask your installer), reachable on TCP port 502. A fixed IP and a wired LAN are recommended.
+- **Python 3.12 or later.**
+
+## Install
+
+The library is not on PyPI yet. To work on it from source:
+
+```bash
+git clone git@github.com:david2069/franklinwh-modbus-async.git
+cd franklinwh-modbus-async
+python3.12 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pre-commit install
+pytest
+```
+
+## Roadmap
+
+| Phase | Scope | State |
+|---|---|---|
+| 0 | Scaffold, CI, PII guard, rationale docs | ✅ |
+| 1 | Connection, SunSpec discovery, generated models, `FakeAGate` | — |
+| 2 | Typed reads and snapshot | — |
+| 3 | Control: M704 dispatch, watchdog, verify, native modes, safety | — |
+| 4 | Virtual modes, TOU schedules, sequencer, discovery | — |
+| 5 | CLI | — |
+| 6 | Emulator and hardware verification | — |
+| 7 | 1.0 release, migration guide | — |
+
+## Documentation
+
+| Page | |
+|---|---|
+| [Why this library](https://github.com/david2069/franklinwh-modbus-async/blob/main/docs/why.md) | Purpose, basis, why async, why modbus-connection, and how it compares with the alternatives |
+| [modbus-connection findings](https://github.com/david2069/franklinwh-modbus-async/blob/main/docs/research/modbus-connection.md) | Notes from reviewing the transport library |
+| [Plan](https://github.com/david2069/franklinwh-modbus-async/blob/main/PLAN.md) | Design decisions and phases |
+| [Changelog](https://github.com/david2069/franklinwh-modbus-async/blob/main/CHANGELOG.md) | |
+
+## Contributing
+
+PRs are welcome. CI runs ruff, mypy `--strict`, pytest and a **PII guard** (`tools/pii_check.py`).
+
+- **Placeholders only.** In code, docs, examples and captured output, use:
+  - `192.0.2.10` for hosts
+  - `FWH-SN-REDACTED` for serials
+  - `00:00:5E:00:53:00` for MAC addresses
+- **Private terms.** Put anything you want blocked in a local `.pii-denylist`. git ignores this file.
+
+## License
+
+MIT. See [LICENSE](https://github.com/david2069/franklinwh-modbus-async/blob/main/LICENSE).

franklinwh_modbus_async-0.0.1/README.md

@@ -0,0 +1,78 @@
+# franklinwh-modbus-async
+
+An **async** Python library for the FranklinWH **aGate**. It talks Modbus TCP and covers the SunSpec models and the vendor extension registers. It is built on [`modbus-connection`](https://github.com/home-assistant-libs/modbus-connection).
+
+This is the asyncio successor to [`franklinwh-modbus`](https://github.com/david2069/franklinwh-modbus), which is synchronous. It aims to match that library's features and to fix its known connection and threading defects. To find out why it exists and how it compares, read **[docs/why.md](https://github.com/david2069/franklinwh-modbus-async/blob/main/docs/why.md)**.
+
+> **Status: pre-alpha (Phase 0 of 7).** The tooling and docs are in place, but there is no device API yet. See [PLAN.md](https://github.com/david2069/franklinwh-modbus-async/blob/main/PLAN.md) for the roadmap.
+
+> ## ⚠️ Unofficial software
+>
+> **About this software**
+>
+> - Not affiliated with, endorsed or supported by FranklinWH. FranklinWH and aGate are trademarks of their owners.
+> - Provided **as is**, without warranty, for educational and informational use.
+>
+> **Write commands carry real risk**
+>
+> - This library can send **write commands to grid-connected battery hardware**.
+> - Used incorrectly, it can discharge your battery when you need it, import power you did not intend to, or leave the system in an unexpected state.
+> - You use it at your own risk.
+>
+> **Getting help**
+>
+> - Do not contact FranklinWH support about this library. Report problems [here](https://github.com/david2069/franklinwh-modbus-async/issues).
+
+## Requirements
+
+- An aGate with **Modbus TCP enabled** (ask your installer), reachable on TCP port 502. A fixed IP and a wired LAN are recommended.
+- **Python 3.12 or later.**
+
+## Install
+
+The library is not on PyPI yet. To work on it from source:
+
+```bash
+git clone git@github.com:david2069/franklinwh-modbus-async.git
+cd franklinwh-modbus-async
+python3.12 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pre-commit install
+pytest
+```
+
+## Roadmap
+
+| Phase | Scope | State |
+|---|---|---|
+| 0 | Scaffold, CI, PII guard, rationale docs | ✅ |
+| 1 | Connection, SunSpec discovery, generated models, `FakeAGate` | — |
+| 2 | Typed reads and snapshot | — |
+| 3 | Control: M704 dispatch, watchdog, verify, native modes, safety | — |
+| 4 | Virtual modes, TOU schedules, sequencer, discovery | — |
+| 5 | CLI | — |
+| 6 | Emulator and hardware verification | — |
+| 7 | 1.0 release, migration guide | — |
+
+## Documentation
+
+| Page | |
+|---|---|
+| [Why this library](https://github.com/david2069/franklinwh-modbus-async/blob/main/docs/why.md) | Purpose, basis, why async, why modbus-connection, and how it compares with the alternatives |
+| [modbus-connection findings](https://github.com/david2069/franklinwh-modbus-async/blob/main/docs/research/modbus-connection.md) | Notes from reviewing the transport library |
+| [Plan](https://github.com/david2069/franklinwh-modbus-async/blob/main/PLAN.md) | Design decisions and phases |
+| [Changelog](https://github.com/david2069/franklinwh-modbus-async/blob/main/CHANGELOG.md) | |
+
+## Contributing
+
+PRs are welcome. CI runs ruff, mypy `--strict`, pytest and a **PII guard** (`tools/pii_check.py`).
+
+- **Placeholders only.** In code, docs, examples and captured output, use:
+  - `192.0.2.10` for hosts
+  - `FWH-SN-REDACTED` for serials
+  - `00:00:5E:00:53:00` for MAC addresses
+- **Private terms.** Put anything you want blocked in a local `.pii-denylist`. git ignores this file.
+
+## License
+
+MIT. See [LICENSE](https://github.com/david2069/franklinwh-modbus-async/blob/main/LICENSE).

franklinwh_modbus_async-0.0.1/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "franklinwh-modbus-async"
+dynamic = ["version"]
+description = "Async FranklinWH aGate Modbus TCP library (SunSpec + extension registers) built on modbus-connection"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "david2069", email = "david2069@users.noreply.github.com" }]
+requires-python = ">=3.12"
+dependencies = [
+    # Pinned tightly: modbus-connection releases roughly weekly and changes
+    # behaviour within minors. Bump deliberately, after the test suite passes.
+    "modbus-connection[tmodbus]~=4.12.4",
+]
+keywords = ["franklinwh", "agate", "battery", "modbus", "sunspec", "asyncio", "energy"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Home Automation",
+    "Topic :: System :: Hardware",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+pymodbus = ["modbus-connection[pymodbus]~=4.12.4"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "pre-commit>=3.7",
+]
+docs = ["mkdocs>=1.6,<2", "mkdocs-material>=9.5"]
+
+[project.urls]
+Homepage = "https://github.com/david2069/franklinwh-modbus-async"
+"Bug Tracker" = "https://github.com/david2069/franklinwh-modbus-async/issues"
+Changelog = "https://github.com/david2069/franklinwh-modbus-async/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "src/franklinwh_modbus_async/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/franklinwh_modbus_async"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+addopts = "--strict-markers"
+markers = [
+    "hardware: needs a real aGate (deselect with -m 'not hardware')",
+    "destructive: writes to a real aGate; also needs --destructive-enabled",
+    "emulator: needs the gateway emulator",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "ASYNC", "RUF"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src", "tools"]
+
+[tool.hatch.build.targets.sdist]
+# PyPI artifacts are public even while the repo is private: ship only what users need.
+include = ["src/", "tests/", "tools/pii_check.py", "README.md", "LICENSE", "CHANGELOG.md", "pyproject.toml"]

franklinwh_modbus_async-0.0.1/src/franklinwh_modbus_async/__init__.py

@@ -0,0 +1,8 @@
+"""Async FranklinWH aGate Modbus TCP library, built on modbus-connection.
+
+Unofficial; not affiliated with or endorsed by FranklinWH. See README.md.
+"""
+
+__version__ = "0.0.1"
+
+__all__ = ["__version__"]

franklinwh_modbus_async-0.0.1/tests/test_package.py

@@ -0,0 +1,13 @@
+import re
+
+import franklinwh_modbus_async
+
+
+def test_version_is_pep440() -> None:
+    pattern = r"\d+\.\d+\.\d+(\.dev\d+|a\d+|b\d+|rc\d+)?"
+    assert re.fullmatch(pattern, franklinwh_modbus_async.__version__)
+
+
+def test_transport_importable() -> None:
+    # The pinned transport and its default (tmodbus) backend must be installed.
+    from modbus_connection.tmodbus import ModbusConnection  # noqa: F401

franklinwh_modbus_async-0.0.1/tests/test_pii_check.py

@@ -0,0 +1,67 @@
+"""Tests for tools/pii_check.py.
+
+Bad samples are assembled at runtime so this file does not trip the guard itself.
+"""
+
+import importlib.util
+import sys
+from pathlib import Path
+
+import pytest
+
+_spec = importlib.util.spec_from_file_location(
+    "pii_check", Path(__file__).parents[1] / "tools" / "pii_check.py"
+)
+assert _spec and _spec.loader
+pii_check = importlib.util.module_from_spec(_spec)
+sys.modules["pii_check"] = pii_check
+_spec.loader.exec_module(pii_check)
+
+
+def kinds(text: str, denylist: tuple[str, ...] = ()) -> list[str]:
+    return [f.kind for f in pii_check.scan_text("x", text, denylist)]
+
+
+@pytest.mark.parametrize(
+    ("text", "kind"),
+    [
+        ("/Us" + "ers/alice/dev/repo", "home path"),
+        ("/ho" + "me/bob/src", "home path"),
+        ("C:" + "\\Users\\carol\\x", "home path"),
+        ("SN " + "12345678" + "A02" + "B12345678", "serial number"),
+        ("mac " + "AA:BB:CC" + ":12:34:56", "MAC address"),
+        ("host " + "192.168" + ".0.50", "IP address"),
+        ("mail " + "someone" + "@gmail.com", "email"),
+    ],
+)
+def test_flags_pii(text: str, kind: str) -> None:
+    assert kinds(text) == [kind]
+
+
+@pytest.mark.parametrize(
+    "text",
+    [
+        "host 192.0.2.10 port 502",
+        "mac 00:00:5E:00:53:00",
+        "loopback 127.0.0.1 and 0.0.0.0",
+        "david2069@users.noreply.github.com",
+        "serial FWH-SN-REDACTED",
+        "modbus-connection~=4.12.4 and version 0.0.1",
+        "the `/Users/` and `/home/` prefixes are blocked",
+        "x " + "192.168" + ".0.50  # pii: allow",
+    ],
+)
+def test_allows_placeholders(text: str) -> None:
+    assert kinds(text) == []
+
+
+def test_denylist_is_case_insensitive_and_redacted() -> None:
+    findings = list(pii_check.scan_text("x", "Written by JANE Example", ["jane example"]))
+    assert [f.kind for f in findings] == ["denylisted term"]
+    assert findings[0].text == "<redacted>"
+
+
+def test_denylist_from_env(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    (tmp_path / ".pii-denylist").write_text("# comment\nalpha\n\n", encoding="utf-8")
+    monkeypatch.setenv("PII_DENYLIST", "beta, gamma")
+    assert pii_check.load_denylist(tmp_path) == ["alpha", "beta", "gamma"]

franklinwh_modbus_async-0.0.1/tools/pii_check.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Fail if tracked files contain personal or site-identifying data.
+
+Checks every file git would commit (tracked plus untracked-but-not-ignored) for:
+
+- home-directory paths (macOS, Linux, Windows)
+- FranklinWH aGate serial numbers (20 chars: 8 digits, letter, 2 digits, letter, 8 digits)
+- MAC addresses other than the RFC 7042 documentation range
+- IPv4 addresses other than loopback, unspecified and RFC 5737 documentation ranges
+- email addresses other than noreply and example domains
+- any term in the local, gitignored ``.pii-denylist`` (one per line, case-insensitive),
+  plus terms in the ``PII_DENYLIST`` environment variable (comma-separated, for CI secrets)
+
+The denylist lives outside git so the things it blocks (for example a real name) are never
+committed. A line can opt out with the marker ``pii: allow``; use it sparingly and only for
+placeholders the patterns misjudge.
+
+Exit status: 0 clean, 1 findings.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import os
+import re
+import subprocess
+import sys
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+ALLOW_MARKER = "pii: allow"
+DENYLIST_FILE = ".pii-denylist"
+
+HOME_PATH = re.compile(r"(?:/Users/|/home/|[A-Za-z]:\\Users\\)[A-Za-z0-9._-]+")
+SERIAL = re.compile(r"\b\d{8}[A-Z]\d{2}[A-Z]\d{8}\b")
+MAC = re.compile(r"\b(?:[0-9A-Fa-f]{2}[:-]){5}[0-9A-Fa-f]{2}\b")
+IPV4 = re.compile(r"(?<![\d.])(?:\d{1,3}\.){3}\d{1,3}(?![\d.])")
+EMAIL = re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}")
+
+DOC_NETWORKS = tuple(
+    ipaddress.ip_network(n)
+    for n in ("192.0.2.0/24", "198.51.100.0/24", "203.0.113.0/24", "127.0.0.0/8", "0.0.0.0/32")
+)
+DOC_MAC_PREFIX = "00:00:5e:00:53"
+ALLOWED_EMAIL_SUFFIXES = (
+    "@users.noreply.github.com",
+    "@noreply.anthropic.com",
+    "@example.com",
+    "@example.org",
+    "@example.net",
+    "@github.com",
+)
+
+
+@dataclass(frozen=True)
+class Finding:
+    path: str
+    line: int
+    kind: str
+    text: str
+
+    def __str__(self) -> str:
+        return f"{self.path}:{self.line}: {self.kind}: {self.text}"
+
+
+def _ip_allowed(text: str) -> bool:
+    try:
+        ip = ipaddress.ip_address(text)
+    except ValueError:
+        return True  # not an address (e.g. 999.1.1.1): not our concern
+    return any(ip in net for net in DOC_NETWORKS)
+
+
+def scan_text(path: str, text: str, denylist: Iterable[str] = ()) -> Iterator[Finding]:
+    terms = [t.lower() for t in denylist if t]
+    for lineno, line in enumerate(text.splitlines(), start=1):
+        if ALLOW_MARKER in line:
+            continue
+        for m in HOME_PATH.finditer(line):
+            yield Finding(path, lineno, "home path", m.group())
+        for m in SERIAL.finditer(line):
+            yield Finding(path, lineno, "serial number", m.group())
+        for m in MAC.finditer(line):
+            if not m.group().lower().replace("-", ":").startswith(DOC_MAC_PREFIX):
+                yield Finding(path, lineno, "MAC address", m.group())
+        for m in IPV4.finditer(line):
+            if not _ip_allowed(m.group()):
+                yield Finding(path, lineno, "IP address", m.group())
+        for m in EMAIL.finditer(line):
+            if not m.group().lower().endswith(ALLOWED_EMAIL_SUFFIXES):
+                yield Finding(path, lineno, "email", m.group())
+        lowered = line.lower()
+        for term in terms:
+            if term in lowered:
+                yield Finding(path, lineno, "denylisted term", "<redacted>")
+
+
+def load_denylist(root: Path) -> list[str]:
+    terms: list[str] = []
+    f = root / DENYLIST_FILE
+    if f.is_file():
+        for raw in f.read_text(encoding="utf-8").splitlines():
+            term = raw.strip()
+            if term and not term.startswith("#"):
+                terms.append(term)
+    terms += [t.strip() for t in os.environ.get("PII_DENYLIST", "").split(",") if t.strip()]
+    return terms
+
+
+def candidate_files(root: Path) -> list[Path]:
+    out = subprocess.run(
+        ["git", "ls-files", "-z", "--cached", "--others", "--exclude-standard"],
+        cwd=root,
+        check=True,
+        capture_output=True,
+    ).stdout
+    return [root / p for p in out.decode().split("\0") if p]
+
+
+def main(argv: list[str] | None = None) -> int:
+    root = Path(argv[0]) if argv else Path.cwd()
+    denylist = load_denylist(root)
+    findings: list[Finding] = []
+    for file in candidate_files(root):
+        if not file.is_file():
+            continue  # deleted in the working tree
+        try:
+            text = file.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            continue  # binary; images need a manual check
+        findings.extend(scan_text(str(file.relative_to(root)), text, denylist))
+    for f in findings:
+        print(f)
+    if findings:
+        print(
+            f"\npii_check: {len(findings)} finding(s). Replace with placeholders "
+            "(192.0.2.10, FWH-SN-REDACTED, 00:00:5E:00:53:00).",
+            file=sys.stderr,
+        )
+        return 1
+    print(f"pii_check: clean ({'with' if denylist else 'no'} denylist)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))