feat: field metadata option + cross-language registry generators (supersedes #905)

[jamesarich]

What & why

Some schema fields carry app/UI-relevant metadata — e.g. GPIO pins that only matter on DIY hardware, which apps want to hide on pre-assembled boards. This adds a first-class, structured way to declare that metadata in the schema and consume it from every client, with no reflection and no runtime cost.

Supersedes #905 (@jp-bennett's experiment). That PR proved the idea with a scalar (meshtastic.diy_only) option; this generalizes it into one extensible FieldMetadata message carried in a single FieldOptions extension, plus the generators that actually expose it to consumers.

How it works

• Source of truth — meshtastic/field_metadata.proto: a structured FieldMetadata message (diy_only, admin_only, min/max_value, unit) carried in one extend google.protobuf.FieldOptions { field_metadata = 51001 }. config.proto's rx_gpio/tx_gpio are annotated { diy_only: true }.
• Why codegen, not runtime reflection — nanopb (firmware), Wire (KMP), and prost (Rust) all strip options at runtime, so reflection can't serve them. Build-time codegen is the only mechanism that works for every consumer (the same approach Google's SDK generators use for google.api.field_behavior).
• Two generators, one shape:
  • KMP/Wire — a Wire SchemaHandler in packages/kmp/buildSrc emits a FieldMetadataRegistry into the published artifact.
  • C / Python / TypeScript / Rust / Swift — tools/protoc-gen-fieldmeta, a protoc/buf plugin (reads the option dynamically; generic over FieldMetadata's fields).
• Each target gets a typed accessor (idiomatic per language) plus a dynamic get(type, tag) fallback. Where the language can extend the real generated message type it does (Kotlin companion extension, Swift type extension); TS/Python use a namespace, Rust a module, C a lookup table.

Accessing it (example: rx_gpio → diy_only)

Language	Accessor
Kotlin	Config.PositionConfig.rx_gpio.diy_only
Swift	Config.PositionConfig.rxGpio.diyOnly
TypeScript	FieldMeta.Config.PositionConfig.rxGpio.diyOnly
Python	fm.Config.PositionConfig.rx_gpio["diy_only"]
Rust	fm::config::position_config::RX_GPIO.diy_only
C	meshtastic_field_metadata_get("meshtastic.Config.PositionConfig", 8)->diy_only

Adding metadata later

Schema-only: add a scalar field to FieldMetadata (next field number) → every target regenerates automatically. No generator/build changes, no new extension number consumed. Non-scalar attributes are a hard error at generation time. (Documented in field_metadata.proto's header.)

Testing performed

• buf lint / buf build / buf breaking vs master — clean (additive change).
• tools/protoc-gen-fieldmeta: gofmt / go vet / go test green (~92% coverage). Tests include an in-memory, buf-faithful end-to-end decode, the scalar-only guard, value rendering (incl. integral floats), string escaping, and multi-message cases.
• Compiled the generated output for all six targets: KMP (compileKotlinJvm), C (clang -Wall -Wextra), Python, Swift (swiftc -typecheck), TypeScript (tsc --strict), Rust (rustc -D warnings).
• buf generate produces field_metadata_registry.ts, re-exported from mod.ts as FieldMeta.

Draft — open items / for review

• Wired and verified for the in-repo TS + KMP packages. The C/Python/Swift/Rust outputs are compile-verified but go live once each consumer repo adds the plugin to its codegen (recipes in tools/protoc-gen-fieldmeta/README.md).
• @jp-bennett — keen on your review since this builds on Experminental PR for adding metadata to protobufs #905, especially: the FieldMetadata shape (which attributes to standardize), the 51001 extension number (keep it in the 50000–99999 in-house range, or request a global-registry number for a public schema?), and the Swift integration assumptions (validated against a stub, not yet real swift-protobuf output).
• The full multi-target packages/kmp build runs in CI on this PR.

🤖 Generated with Claude Code

[github-actions]

The latest Buf updates on your PR. Results from workflow pull-request / build (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	✅ passed	✅ passed	❌ failed (23)	Jul 19, 2026, 8:48 PM

[jamesarich]

Heads-up on the red build check: it's failing only on buf format for meshtastic/powermon.proto — unrelated to this PR. buf-action runs the latest buf (now 1.71.0), which reformats that file's block comments; master's last green run predated 1.71.0, so it's repo-wide drift. This PR's own files (config.proto, field_metadata.proto) are format-clean. Fixed separately in #953 — once that merges, this PR's check clears on a rebase onto master. Keeping this draft focused on the field-metadata design for review. /cc @jp-bennett

[garthvh]

Validated the Swift side from the Meshtastic-Apple end — two findings.

1. The Swift integration assumption holds against real swift-protobuf output (closing the "validated against a stub" open item):

• Built protoc-gen-fieldmeta from this branch (go test green), generated FieldMetadataRegistry.swift via protoc over this branch's schema.
• Dropped it into Meshtastic-Apple's real MeshtasticProtobufs package (swift-protobuf 1.36.1, the app's pinned version) next to the actual generated config.pb.swift → swift build clean.
• An external consumer file typechecks against the built module:

let isDiy: Bool? = Config.PositionConfig.rxGpio.diyOnly                 // typed accessor ✓
FieldMetadataRegistry.get("meshtastic.Config.PositionConfig", tag: 8)   // dynamic lookup ✓
var config = Config.PositionConfig()
config.rxGpio = 7                                                        // real instance property
(config.rxGpio, Config.PositionConfig.rxGpio.diyOnly)                    // static + instance coexist ✓

That last line was the collision case worth worrying about (generated static var rxGpio alongside the real instance property rxGpio) — Swift resolves both cleanly. The README's gen_protos.sh recipe is accurate as written.

2. A pure-Swift implementation of the generator produces byte-identical output. As an experiment in keeping the Apple pipeline Go-free, I wrote the same generator (~180 lines) on SwiftProtobufPluginLibrary — the library protoc-gen-swift itself is built on:

• customOptionExtensions exposes (meshtastic.field_metadata) as a typed value on field.options — no manual descriptor/unknown-fields work.
• Type paths and property names come from SwiftProtobufNamer/NamingUtils — the same naming engine that generated the app's .pb.swift — so rx_gpio → rxGpio (and less obvious cases like pm10_standard) can't drift from real generated code by construction, rather than by reimplementing the casing rules.
• Output over this branch's schema is byte-for-byte identical to the Go plugin's (diff clean), and it passes the same MeshtasticProtobufs build + consumer typecheck.
• Parity kept: schema-driven struct shape (new scalar attributes flow through), the scalar-only hard error. One difference: value-literal emission is an explicit switch over the current attributes with a loud failure on unknowns (one-line to extend), vs. the Go plugin's fully dynamic rendering — could be made dynamic too.

Happy to contribute it as tools/protoc-gen-fieldmeta-swift on this branch (or a follow-up) if there's appetite for a first-party no-Go path for swift-protobuf consumers — otherwise it can live in Meshtastic-Apple alongside gen_protos.sh. Either way, the design here works for Swift: 👍 from the Apple side.

[jamesarich]

feel free to push changes here @garthvh

[garthvh]

Looks like it will work, I have swift tooling

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 760c97a3-b902-48af-bb04-3aec4cff4ab6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch jamesarich/field-metadata

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[garthvh]

Pushed the Swift implementation onto this branch as offered: tools/protoc-gen-fieldmeta-swift (aede581).

• Same registry, byte-identical output to protoc-gen-fieldmeta's target=swift (verified on swift-protobuf 1.36.1 and 1.38.1) — the two are interchangeable; this one keeps swift-protobuf consumers Go-free.
• Naming comes from SwiftProtobufPluginLibrary's own SwiftProtobufNamer/NamingUtils (the engine protoc-gen-swift uses), and the option arrives typed via customOptionExtensions.
• Includes the plugin's generated field_metadata.pb.swift binding (regen recipe in its README), a cross-link from the Go plugin's Apple section, and a .gitignore entry for its .build/.
• One deliberate divergence, documented in the README: value emission is an explicit per-attribute switch that fails loudly on an unhandled attribute (one-line to extend) instead of fully dynamic rendering — happy to make it dynamic if you'd rather have exact behavioral parity there.

Feel free to reshape/drop anything that doesn't fit the PR's direction.

[garthvh]

Can we mirror the deprecated field info I can't currently read here?