initial commit

AGENT.md

@@ -0,0 +1,56 @@
+# Project notes for agents working on this repo
+
+## What this is today
+
+A Python PoC that scrapes and writes to an HP ProCurve/OfficeConnect 1810 (J9450A)
+switch's built-in web UI at `192.168.2.10` (no auth configured on the switch).
+
+- `switch_client.py` — session/login (`get_session()`), generic `fetch()` (GET) and
+  `submit_form()` (POST, for writes).
+- `extractors/xe_page.py` — generic parser for the firmware's auto-generated ("XE") pages;
+  every page renders one of two table shapes (scalar key/value, or tabular with headers),
+  values always sit inside hidden `<INPUT VALUE=...>` tags. Both reads and writes rely on
+  this same parser.
+- `extractors/*.py` — one `get_x(session)` read function per switch data page.
+- `actions/*.py` — one `get_x_state(session)` / `set_x(session, value)` pair per writable
+  setting (currently just `locator.py`).
+- `todo.py` / `TODO.md` — tracks which menu items have a read extractor implemented.
+
+## Long-term goal: become a Terraform module
+
+The intended end state is a Terraform provider/module for this switch (and possibly the
+pattern generalized to similar switches). Terraform's core flow — as far as understood
+right now, exact provider-SDK details not yet researched — is: **read current state →
+diff against declared (desired) state → apply only the difference**. Each switch setting
+(Locator, System Name, VLAN config, port config, ...) should eventually become a Terraform
+resource with that Read/Diff/Apply semantics.
+
+This is **not** an active task — no provider scaffolding, no SDK choice, no `ensure()`
+helper exists yet. It's noted here so code written in the meantime doesn't need reshaping
+later.
+
+### What this means for code written now
+
+When adding a new `get_x`/`set_x` pair in `actions/`:
+
+- `get_x_state(session)` must be a pure read — no side effects, safe to call anytime.
+- `set_x(session, value)` should be idempotent — calling it again with the same `value`
+  it already holds should be harmless, not something the caller has to guard against
+  externally. (Not yet enforced anywhere; `actions/locator.py` always writes regardless of
+  current state — fine for a manual on/off toggle, but a future idempotent version would
+  read first and skip the write if already at `value`.)
+- Keep `get_x_state` and `set_x` as separate, independently callable functions rather than
+  a combined "set and forget" call — that split is exactly what a Terraform resource's
+  Read and Update map onto.
+
+### Explicit non-goals right now
+
+- No Terraform provider code, scaffolding, or SDK/language decision (Go provider vs.
+  something else) exists yet.
+- No generic `ensure(desired) -> read, diff, apply-if-different` helper exists yet either —
+  that's a natural next step once more `actions/` modules exist, but shouldn't be built
+  speculatively ahead of need.
+
+Next concrete step towards this goal, when picked up: look into what a Terraform
+provider's Read/Diff/Apply contract actually requires (e.g. Terraform Plugin Framework)
+before designing anything here around it.