feat(framework): the Lua API declared once, require and api_version

[sp00ktober]

For sp00ktober/MHFU-ModKit#66.

• One declaration, lua/meta/mhfu.d.lua (---@meta), covers the 80 bindings, their constants, and the types of the event contexts and em_* tables, each with a doc line. tools/lua_api.py renders the registered table from it. Drift fails the build:
  • a binding defined but not declared fails the compile (-Werror=missing-declarations);
  • one declared but not defined fails the link;
  • each constant is static_asserted against its C name.
• LuaLS: .luarc.json at the root (Lua 5.4, no io/os/debug). The prelude is annotated in place and embedded with its annotation lines blanked. A new CI job runs a pinned lua-language-server --check over all shipped Lua.
• require: Lua's package library with one searcher, for mods/lib/<name>.lua; C loading and path search are removed.
  • A library that was required and then changes is re-run in place.
  • After boot, a library that is not loaded yet is read only during gameplay.
• mhfu.api_version is 1 and logged on VM ready.
• Scripts sorted:
  • lua/lib/: _prelude.lua, and mhfu_port.lua, now a library (port = require("mhfu_port"); the _queue global is gone);
  • lua/tools/: cli_bridge.lua;
  • lua/examples/: action override, second monster, ported Brute.
• Boot errors visible: held log lines are written right after the boot script load, so a compile error reaches framework.log without entering a quest.
• Freecam's seven bindings leave the API until freecam is installed (Freecam: its own toggle, then install it and give it back its Lua API #24).

Documented as they are, not fixed here:

• mhfu.player_pos returns the camera eye;
• a second Lua handler on an event replaces the first.

Test plan

• uv run pytest, pre-commit run --all-files, clean make -C framework, LuaLS clean
• A binding declared but not defined, and one defined but not declared, each fail the build
• PPSSPP cold boot, after approval:
  • api=1 appears on VM ready;
  • a broken script's error shows up in framework.log while in the village;
  • mhfu_port loads through require and hot-reloads;
  • each example runs in a Giadrome quest

🤖 Generated with Claude Code