feat(drivers): let a driver declare the commands an operator may send

[frahlg]

Answers the "does the driver need to declare something extra?" half of #520. Today the answer is no — there is nothing to declare. This adds it.

The gap

Settings → Devices renders hand-written branches per driver family (devices.js:23 says so: the choices stay there "until the signed driver catalog grows a general config-schema field"). So a driver with a real control surface cannot describe it. The Heishamon heat pump has had a hardware-verified set_heat_curve_offset since June, and its author was told to drive it from a Home Assistant automation instead.

Signed packages already carry this shape in RuntimeCommand — typed inputs, lease policy, evidence — but only for drivers on the signed channel. rd.policy is nil for every bundled and local driver, so the DRIVER block is where their declaration has to live.

What this adds

  controls = {
    {
      id       = "set_heat_curve_offset",
      label    = "Heat curve offset",
      evidence = "readback",
      input    = { type = "number", min = -3, max = 3, step = 1, unit = "°C" },
    },
  },

Surfaced on /api/drivers/{name} and /api/drivers/catalog.

Nothing sends these commands. This is the description; the command path is separate work and is where the interesting problems are (lease expiry runs driver_default_mode, which for heishamon writes the offset back to safe — so a manual setting needs a Core-side hold with heartbeat renewal, since Lease.MaxDuration caps at 300 s).

Notes for review

• The parser is the real change. pickKVBlock matches [^}]* and stops at the first closing brace; pickString anchors to the start of a line. Both are right for flat fields and both break on a nested list written inline. This reads controls with its own brace matching rather than changing how every other field is parsed. TestBundledCatalogStillParses covers the regression that would matter — a controls reader that quietly eats an unrelated field.
• Unrenderable declarations are dropped, not surfaced. No id, a type outside number/boolean/string, or a number missing either bound. A slider with one end is a guess, not a control.
• Bounds are pointers because zero is a real bound — a 0..100 percentage and an undeclared range must not read the same.
• The JSON key stays absent for drivers that declare nothing, so a client can tell "reports only" from "declares an empty list".
• Path matching follows IsEVOrVehicleDriver/IsReadOnlyDriver: portable path first, then filename. Operators write drivers/x.lua and /data/x.lua both.

No bundled driver declares controls yet — drivers/ is a generated snapshot and cannot be edited here. Adding the block to heishamon is a device-drivers change, after srcfl/device-drivers#60.

make verify clean.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fa3148ce30

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[miravoss26]

Read the whole diff — a driver can now declare operator-facing controls in its DRIVER block, surfaced read-only via /api/drivers/{name} and the catalog. Nothing dispatches them yet; this is the description, not the path. Clean and unusually well-tested.

Correctness

• The hand-rolled brace matcher (nestedBlock/topLevelTables) is the right call given the existing pick helpers stop at the first }, and it's string-aware — a { inside a label doesn't truncate the table (TestControlsSurviveBraceInsideString). It doesn't handle escaped quotes or Lua long-brackets, but the comments scope that out for metadata, which is fair.
• fieldString/fieldNumber's (?:^|[\s,{])name\s*= boundary correctly stops min from matching inside minimum — the \s*= suffix does the real work there.
• Pointer bounds (*float64) so 0 stays distinguishable from "unset" is exactly right, and tested. Drop-if-unrenderable (no id / bad type / single or inverted bound / bad evidence) keeps a half-formed control off the operator's screen.

One note, not a blocker: driverControls calls LoadCatalogMulti (a full catalog parse from disk) on every /api/drivers/{name} request. Fine for a settings-UI call; worth a cache only if it ever lands on a hot path.

Security screen: no secrets, no new deps, no network, no authz change — and nothing commands the device yet, so the blast radius is a read surface. regexp.QuoteMeta guards the field-name interpolation (all literals today anyway); the regexes are linear, no ReDoS.

CI green, coverage thorough. Safe to merge from my read — leaving the merge to a human (ftw isn't on my auto-merge allowlist).