hp-iac/AGENT.md

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

- `config.py` — connection config from env vars (`SWITCH_HOST`, `SWITCH_HTTPS`,
  `SWITCH_PASSWORD`). These three map directly onto what a future Terraform provider's
  config block would need per-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 provider (full Go rewrite)

The intended end state is a real Terraform provider for this switch. Researched and
decided: Terraform's plugin protocol requires Go (HashiCorp's Terraform Plugin Framework
is the current recommended SDK — see sources below), and the plan is a **full rewrite in
Go**, not a thin Go shell calling out to this Python code. This Python project stays as-is
as the reference implementation the Go port gets verified against.

**Correction to an earlier assumption**: Terraform **Core** does the diffing itself
(compares saved state vs. declared config via the resource's schema) — the provider does
NOT need its own `ensure()`/diff mechanism. It only implements:
- **Read**: fetch real current state → write into Terraform state.
- **Update**: called by Core only when Core already determined there's a difference.

This still supports the existing guideline below (keep `get_x`/`set_x` separate, `set_x`
idempotent) — just for a different reason than originally assumed: not because the
provider diffs, but as a safety net against config drift (someone changes the switch via
its web UI between `terraform plan` and `apply`).

Sources: [Terraform Plugin Framework (pkg.go.dev)](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework),
[Resources — HashiCorp Developer](https://developer.hashicorp.com/terraform/plugin/framework/resources),
[Implement a provider with the Plugin Framework (tutorial)](https://developer.hashicorp.com/terraform/tutorials/providers-plugin-framework/providers-plugin-framework-provider).

### CLI tooling: OpenTofu, not Terraform

The user is installing **OpenTofu** (`tofu` CLI) rather than the Terraform CLI. This
doesn't change any of the Go code below — OpenTofu speaks the same plugin protocol as
Terraform, and a provider built with `terraform-plugin-framework`/`terraform-plugin-go`
(there's no separate "OpenTofu SDK") works unmodified against it. Practical differences
only: the CLI binary is `tofu`, and local dev-override config lives in `~/.tofurc`
(env var `TF_CLI_CONFIG_FILE` also works) instead of `~/.terraformrc`. "Terraform
state"/"Terraform Core" below refers to the shared plugin-protocol concepts, which apply
identically under OpenTofu.

### The plan

New sibling Go module: `~/code/experiments/terraform-provider-hpe1810/` (separate
toolchain/`go.mod`, not nested in this Python project), scaffolded from HashiCorp's
`terraform-provider-scaffolding-framework` template.

- `internal/provider/client/client.go` — port of `switch_client.py` (`net/http.Client` +
  `net/http/cookiejar` for session cookies; same login POST fields, same GET-before-POST
  workaround, same `submit_flag=8` fix in `SubmitForm`). **Simplification vs. Python**: the
  provider process lives for the whole `terraform plan`/`apply` run, so the disk-cached
  session (`.session_cookie`) mostly goes away — `Configure()` logs in once, the same
  client is reused for every resource/data source in that run. The switch's single-session
  limit still means don't run two `terraform` processes against it concurrently.
- `internal/provider/client/xepage.go` — port of `extractors/xe_page.py`, using `goquery`
  (closest Go equivalent to BeautifulSoup). Same two table shapes (scalar
  `defleft`/`defright`, tabular via `<TH>`), same duplicate-header caveat as a comment.
- `provider.go` schema maps 1:1 onto `config.py`'s three fields (`host`/`https`/`password`),
  with the same env var fallback pattern already established there.
- One data source per current `extractors/*.py` (`system_description`, `network_setup`,
  `port_summary`, `lldp_statistics`, `buffered_log`, `mac_table`, `trunk_status`,
  `loop_protection_status`, `dual_image_status`, `clock`, `sntp`, `log_configuration`,
  `backup_manager`).
- One resource per current `actions/*.py` (just `locator` today) — singleton-setting
  resource with a fixed state ID. `Delete` semantics are decided **per resource**, not by
  one blanket rule — the guiding question is "what's the safest state for *this* setting
  to end up in", which sometimes means actively changing something, not just leaving it or
  resetting to a factory default:
  - **Locator**: reset to `Disable` — harmless, and leaving a physical LED blinking after
    `terraform destroy` would be confusing.
  - **Port Configuration**: `Delete` should disable/close the port — an unmanaged port is
    a security exposure, so "no longer managed by Terraform" should fail toward *safer*
    (closed), not toward "whatever it happened to be".
  - **Network Setup** (IP, gateway, SNMP, management VLAN): `Delete` should be a pure
    no-op that only drops it from Terraform state — there's no safe "unset" state for
    the switch's own management network config; touching it on delete risks the same
    lockout the risk triage below already warns about.
  Decide this explicitly for each resource as it's built, using this "what does *safe*
  mean for this specific setting" question — don't default to a single project-wide rule.
- Testing: unit tests for `xepage.go` against `page_snapshots/*.html` copied into
  `testdata/` (already-collected golden fixtures, runnable offline); acceptance tests via
  `terraform-plugin-testing`, gated behind `TF_ACC=1`, only runnable against the real
  switch.
- Suggested build order: scaffold + `Configure()` → one vertical slice end-to-end
  (`data.hpe1810_system_description`) → remaining data sources → `resource_locator` →
  further write resources in the risk-triage order below (Safe category first).
- **Status (2026-08-25)**: all 13 data sources are ported and verified with a live
  `tofu plan` against the real switch (`~/code/experiments/hpe/terraform/`) — confirmed
  port 24 (the active uplink) reads `Link Up`, all other ports `Link Down`. Only
  `resource_locator` (and further write resources) remain unbuilt.

### What this means for code written in this Python project meanwhile

Even though the Go rewrite won't call this code directly, keep the same shape so the port
stays a straight translation:

- `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 yet enforced anywhere; `actions/locator.py`
  always writes regardless of current state — fine for a manual on/off toggle.)
- Keep `get_x_state` and `set_x` as separate, independently callable functions — that
  split is exactly what a Terraform resource's Read and Update map onto.

### Explicit non-goals right now

- No Go module has been created yet — this is still just a plan.
- No generic `ensure(desired) -> read, diff, apply-if-different` helper needed in Python
  either now, given Core does the diffing in the real provider.

## Offline snapshots

`page_snapshots/` holds raw HTML + per-page `_xe_*.js` (field names/types/enums/OIDs) for
every menu page, captured while the switch was reachable, plus `current_state.json` (a
dump of every extractor's output at capture time) and `manifest.json` (HTML/JS file
mapping). Use these to write and offline-verify new `extractors/`/`actions/` modules
(parse the saved HTML directly, no live switch needed) when the switch isn't reachable —
just re-verify against the real switch once it's back online, since a snapshot can go
stale (config changes, firmware updates).

## Write-target risk triage (for future `actions/` modules)

Assessed from the snapshotted HTML/JS, not yet attempted live. Categorized by how bad a
mistake would be and how easy it is to recover from.

**Safe** (cosmetic or trivially reversible, like `actions/locator.py`):
- Green Features (`greenmode.html`) — EEE power-saving toggle, no traffic impact.
- Ping Test (`Ping.html`) — triggers a diagnostic ping, doesn't change config.
- Jumbo Frames (`JumboFrames.html`) — single global MTU toggle, reversible.

**Moderate** (affects real behavior, recoverable if you're paying attention, but a bad
value has a real consequence — treat these with a real read-before-write / dry-run, not
a blind toggle):
- LLDP Configuration, Loop Protection Config, Port Mirroring (`FDBConfig.html`),
  Flow Control (`SwitchConfig.html`), Trunk Configuration/Membership.
- Time Zone / Daylight Saving Time config — wrong values just show wrong time, not
  dangerous, but affects log timestamps everywhere.

**High risk — plan for a lockout, not just "recoverable"**:
- **Port Configuration** (`PortConfiguration.html`): disabling/misconfiguring the port
  your management traffic actually flows over locks you out over the network (physical
  access to the switch would be needed to recover).
- **VLAN Configuration / VLAN Ports / Participation** (`VlanCreateConfig.html`,
  `VLANPortConfig.html`, `VLANPortParticipation.html`): misconfiguring the management
  VLAN or tagging is one of the most common ways to lock yourself out of a switch
  entirely.
- **Advanced Security / Secure Connection** (`security.html`, `SSLCfg.html`): e.g.
  forcing HTTPS-only or an access-control change could cut off the very HTTP session
  this project depends on.

**Dangerous — do not automate without explicit, per-run human confirmation, ever**:
- Reboot Switch (`SystemReset.html`) — drops all connections, however briefly.
- Factory Defaults (`ResetConfigToDefaults.html`) — wipes all configuration.
- Password Manager (`UserAccounts.html`) — setting/losing the admin password on a switch
  that currently has none configured is exactly the kind of mistake that requires a
  factory reset (or worse) to undo.
- Update Manager / firmware upload (`http_file_download.html`) — a bad image can brick
  the switch.
- Dual Image Configuration (`dual_image_cfg.html`) — changes which firmware image boots
  next; combined with a reboot this has the same blast radius as a firmware update gone
  wrong.
- Save Configuration (`SaveAllChanges.html`) — not destructive by itself (persists
  running-config to startup-config, standard practice on this class of switch), but it's
  what turns every other write above from "revert on next reboot" into permanent —
  never call this automatically as a side effect of something else.

Recommended order for future write targets, safest-value first: Green Features → Jumbo
Frames → Ping Test → LLDP/Loop Protection/Trunk config → Port Configuration → VLANs. Treat
everything in "Dangerous" as out of scope for automation entirely unless the user
explicitly asks for that specific action, and even then prefer a human-confirmed,
one-off script over a reusable `actions/` module.