# 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.