refactor(amuleapi): self-explanatory /preferences names, one schema table, Web UI label CI gate (#655) - #696

Closes #655.

Acts on ngosang's field-by-field review of GET /api/v0/preferences: 46 of the 119 fields change name or position so that each one states what it does without a lookup table, and the three code paths that describe those fields collapse into one declarative table. 73 fields were already fine and are untouched.

Since amuleapi has not shipped and the protocol stays at v0, the old names are removed outright rather than dual-emitted. There is no compatibility shim to carry or remove later.

The EC protocol is unchanged. Every tag number, presence-vs-value encoding and thePrefs:: accessor stays exactly as it was, so amulegui, amulecmd and amuleweb are unaffected. All of the translation happens at the webapi boundary, the same way extended_udp_port_enabled already inverted EC_TAG_CONN_UDP_DISABLE before this PR.

Three commits

1. Field names. Renames grouped by the problem each one fixes, following the issue's rules: positive names only, units in the name, no abbreviations.

• Actively misleading: security.obfuscation_supported → obfuscation_enabled (it is a writable preference, whereas _supported / _available elsewhere in the payload means a read-only build capability, so a client filtering on that suffix would silently drop it); message_filter.friends / .secure / .all → accept_from_friends_only / accept_from_known_clients_only / filter_all_messages; directories.exclude_regex → exclude_patterns_use_regex, which is a modifier on exclude_patterns rather than a second exclusion list.
• Missing units: core_tweaks.srv_keepalive_timeout → server_keepalive_timeout_ms (its two siblings in the same object already said _ms), plus upload_slot_kbps, file_buffer_bytes, update_frequency_seconds, refresh_seconds.
• Magic numbers: connection.proxy_type and security.can_see_shares (now shared_files_visibility) become enum strings, so no client needs to hardcode the integer tables the Web UI used to carry.
• Structure: remote_controls.{webserver,amuleapi}.{...} replaces nine webserver_* / amuleapi_* prefixes. Both sub-objects still pack into the single EC_TAG_PREFS_REMOTECTRL group — the nesting is an API shape, not an EC one.

The Web UI moves in the same commit: field keys, the derived prefs_field_* dictionary entries in both locales, and dotted category paths for the nested objects. Two labels copied verbatim from the desktop dialog are reworded ("Slot Allocation" → "Upload speed per slot (KB/s)"), and the keepalive field now scales to minutes like the desktop slider instead of rendering a bare millisecond count.

2. One schema table. The 119 fields were described three times in three different idioms — a hand-written EC decode per category, a w.Key/w.Value pair per field, and a PATCH applier that had grown two parallel helper families (87 call sites on the generic PrefTake* helpers plus 22 more on connection-local lambdas doing the same job with their own error strings and a different return convention). A field touched in two of the three and missed in the third compiled cleanly. That is the failure mode this rename pass would have been most exposed to.

All three now walk one table in src/webapi/PrefsSchema.cpp. Adding a preference is one row; renaming one is one token. What used to be special-case code became a column: invert, the presence-vs-value encoding, read-only/write-only/rejected access, the capability gate behind files.mmap_enabled's 409, and the one field whose EC tag lives in a different group than its JSON category implies (connection.upnp_available, serialized into [General]). Rows carry the address of their backing member and the macros static_assert that the declared type matches the member's real C++ type, so a mis-typed row fails the build rather than misbehaving at runtime.

Net −1655 / +1469 lines across the PR, with the preferences handling in Api.cpp down 912 lines and Refresher.cpp down 212.

One field genuinely cannot be described by the table and stays hand-written: remote_controls.webserver.guest_enabled and .guest_password share a single EC tag, which carries the enable bool as its value and the password hash as a child, so there is no 1:1 field-to-tag mapping to record. The schema marks it Bespoke and its GET emission is still table-driven.

3. The sparse-file flag. files.create_normal → files.create_sparse_files, with its meaning inverted — the one field in the payload whose positive name could not be reached by renaming alone.

Every layer except EC already spoke in terms of "sparse": the config key is /eMule/CreateSparseFiles, the core stores s_createFilesSparse (default on), PartFile.cpp reads CreateFilesSparse(), and the desktop checkbox added in #662 is labelled "Create new files as sparse files". Only the EC tag is named for the negative case, and amuleapi was the one consumer republishing that name outward — which is why the Web UI said "non-sparse" where the desktop said "sparse" for the same setting. Doing this after the table meant it was one column rather than two structurally different edits on the read and write paths.

Verification

Equivalence was checked against a GET /preferences captured from the pre-refactor build: the EC decode and the GET emitter each produce byte-identical output, and the final key set matches at 119/119.

The polarity flip was verified against the daemon's own amule.conf rather than the API's echo, since that is precisely where a self-consistent API can still be wrong:

Also: full macOS build clean with no new warnings; ctest 28/28; curl phase 15 (preferences-patch) 117/117 including new coverage for the nested remote_controls shape, both enums and every error path; phases 05 and 20 pass all /preferences assertions. clang-format 18, matching CI.

Two new unit tests pin the table's own invariants — no duplicate fields, every category resolving to an EC group, backing members present exactly where a value round-trips, enum rows carrying a name table, capability gates naming a real sibling bool, and the emitted count holding at the documented 119. A second test enumerates the deliberate irregularities, so a new one has to be added consciously; it caught commit 3 on its own and failed until the inverting fields were listed explicitly.

check-i18n.mjs gains a check that every preferences field resolves to a real label, and is wired into the i18n workflow. Those keys are derived from the field names, so before this a renamed field with no dictionary entry would have rendered the raw key with nothing failing anywhere. It is verified to catch a deliberately broken key.

Notes for review

• Breaking for any client built against the pre-release shape. files.create_sparse_files is the one field where renaming the key without flipping the value produces the opposite behaviour.
• Error bodies are now uniform ("endgame_enabled must be a bool") where they used to be per-category ("connection field must be a bool"). Nothing asserted the old wording.
• JSON key order within each category changed, since emission follows the table. Object key order is not significant, but it does change the ETag once.
• The Web UI's sparse checkbox now renders checked by default where it rendered unchecked, for an unchanged underlying setting.

Two judgement calls where the issue offered options: I kept the ipfilter_ prefix on all six security fields rather than dropping it from two of them, since the issue's own suggestions in A8 and C5 retain it and dropping it would leave security.update_url not saying what it updates; and security.paranoid_filtering became reject_spoofed_source_ips to say what the setting does rather than name the mood.

Found but deliberately not fixed here

Three pre-existing issues surfaced while working through this; none is caused by this PR and each would muddy it. Ready to open separate issues if wanted.

• The Web UI exposes an amuleapi password field under Remote Controls that the backend rejects with 400, since those credentials belong to PATCH /auth/passwords. Predates this work; behaviour is preserved exactly.
• kad.buddy.status is asserted against an enum including "unknown", but the decoder leaves it empty when Kad is not running, so the assertion only holds on a connected node.
• core_tweaks.file_buffer_bytes silently quantizes to 15000-byte steps, because the core stores the value divided by 15000. PATCH 250000 and it reads back 240000. Worth documenting in the API reference.