v0.1.6: implement IDA-style plugins menu and lua API backend

This commit implements the plugin architecture described in docs/plugins.md, allowing users to extend Hyperion with Lua scripts loaded at startup.

Changes include:
- `LuaEngine` Backend: Added internal structures (`PluginEntry`, `PluginMenuItem`) and implemented `load_plugins(dir)` to automatically scan and parse `.lua` scripts from the `plugins/` directory.
- Lua C API Registration: Implemented and registered four new Lua API functions (`register_plugin`, `register_menu_item`, `register_hotkey`, `register_on_analysis_complete`) that interface directly with the plugin registry.
- UI Integration (`App`): Added a "Plugins" menu dynamically populated with flat items (for single-action plugins) and submenus (for multi-action plugins).
- Plugin Manager: Added a new `Plugin Manager...` dialog displaying loaded plugins, descriptions, action counts, and error statuses.
- Execution & Callbacks: Wired `lua_.check_hotkeys()` into the frame loop and `run_analysis_complete_callbacks()` into the analysis handoff to support custom keyboard shortcuts and post-analysis automation safely on the main thread.
- Included `example_plugin.lua` built into the output directory as a working reference.

Author: not1cyyy

.gitignore

@@ -25,3 +25,5 @@ Release/
 *.dll
 hyperion_layout.ini
 imgui.ini
+CONTRIBUTING.md
+SKILL.md

src/scripting/lua_engine.cpp

@@ -1,7 +1,9 @@
 #include "lua_engine.h"
 #include <fmt/format.h>
 #include <spdlog/spdlog.h>
+#include <imgui.h>
 #include <cstring>
+#include <algorithm>
 
 extern "C" {
 #include <lua.h>
@@ -13,6 +15,10 @@ namespace hype {
 
 namespace {
 
+// -----------------------------------------------------------------------
+// Registry helpers
+// -----------------------------------------------------------------------
+
 LuaEngine* get_engine(lua_State* L) {
     lua_getfield(L, LUA_REGISTRYINDEX, "__hype_engine");
     auto* eng = static_cast<LuaEngine*>(lua_touserdata(L, -1));
@@ -34,6 +40,76 @@ PEImage* get_img(lua_State* L) {
     return img;
 }
 
+// -----------------------------------------------------------------------
+// Hotkey parsing helpers
+// -----------------------------------------------------------------------
+
+struct HotkeySpec {
+    ImGuiKey key  = ImGuiKey_None;
+    bool ctrl     = false;
+    bool shift    = false;
+    bool alt      = false;
+};
+
+// Parse strings like "Ctrl+Shift+R", "Alt+F7", "F5", "Ctrl+G"
+HotkeySpec parse_hotkey(const std::string& s) {
+    HotkeySpec spec;
+    std::string token;
+    std::string src = s;
+    // Split on '+'
+    std::vector<std::string> parts;
+    size_t pos = 0;
+    while ((pos = src.find('+')) != std::string::npos) {
+        parts.push_back(src.substr(0, pos));
+        src.erase(0, pos + 1);
+    }
+    parts.push_back(src); // last part
+
+    for (auto& p : parts) {
+        // to lower for comparison
+        std::string lp = p;
+        for (auto& c : lp) c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
+        if (lp == "ctrl")  { spec.ctrl  = true; continue; }
+        if (lp == "shift") { spec.shift = true; continue; }
+        if (lp == "alt")   { spec.alt   = true; continue; }
+
+        // Match ImGuiKey
+        if (p.size() == 1) {
+            char c = static_cast<char>(std::toupper(static_cast<unsigned char>(p[0])));
+            if (c >= 'A' && c <= 'Z')
+                spec.key = static_cast<ImGuiKey>(ImGuiKey_A + (c - 'A'));
+            else if (c >= '0' && c <= '9')
+                spec.key = static_cast<ImGuiKey>(ImGuiKey_0 + (c - '0'));
+        } else if (lp[0] == 'f' && lp.size() <= 3) {
+            // F1–F12
+            int n = 0;
+            try { n = std::stoi(lp.substr(1)); } catch (...) {}
+            if (n >= 1 && n <= 12)
+                spec.key = static_cast<ImGuiKey>(ImGuiKey_F1 + (n - 1));
+        } else if (lp == "space")  { spec.key = ImGuiKey_Space; }
+          else if (lp == "tab")    { spec.key = ImGuiKey_Tab; }
+          else if (lp == "enter")  { spec.key = ImGuiKey_Enter; }
+          else if (lp == "escape") { spec.key = ImGuiKey_Escape; }
+          else if (lp == "delete") { spec.key = ImGuiKey_Delete; }
+          else if (lp == "home")   { spec.key = ImGuiKey_Home; }
+          else if (lp == "end")    { spec.key = ImGuiKey_End; }
+    }
+    return spec;
+}
+
+bool check_hotkey(const HotkeySpec& spec) {
+    if (spec.key == ImGuiKey_None) return false;
+    auto& io = ImGui::GetIO();
+    if (spec.ctrl  != io.KeyCtrl)  return false;
+    if (spec.shift != io.KeyShift) return false;
+    if (spec.alt   != io.KeyAlt)   return false;
+    return ImGui::IsKeyPressed(spec.key);
+}
+
+// -----------------------------------------------------------------------
+// Existing Lua API
+// -----------------------------------------------------------------------
+
 int l_get_name(lua_State* L) {
     auto* db = get_db(L);
     if (!db) { lua_pushnil(L); return 1; }
@@ -102,9 +178,9 @@ int l_get_bytes(lua_State* L) {
 
     for (auto& seg : img->segments) {
         if (!seg.contains(addr)) continue;
-        size_t off = static_cast<size_t>(addr - seg.va);
+        size_t off   = static_cast<size_t>(addr - seg.va);
         size_t avail = seg.data.size() - off;
-        size_t n = static_cast<size_t>(len) < avail ? static_cast<size_t>(len) : avail;
+        size_t n     = static_cast<size_t>(len) < avail ? static_cast<size_t>(len) : avail;
         lua_pushlstring(L, reinterpret_cast<const char*>(seg.data.data() + off), n);
         return 1;
     }
@@ -178,19 +254,104 @@ int l_goto(lua_State* L) {
     return 0;
 }
 
-} // anon
+// -----------------------------------------------------------------------
+// Plugin registration Lua API
+// -----------------------------------------------------------------------
+
+int l_register_plugin(lua_State* L) {
+    auto* eng = get_engine(L);
+    if (!eng) return 0;
+    const char* name = luaL_optstring(L, 1, "Unnamed Plugin");
+    const char* desc = luaL_optstring(L, 2, "");
+
+    // Find the entry that was pre-created for the current file, or create one
+    auto& plugins = const_cast<std::vector<PluginEntry>&>(eng->plugins());
+    for (auto& p : plugins) {
+        if (p.path == eng->current_plugin_name()) {
+            p.name = name;
+            p.desc = desc;
+            return 0;
+        }
+    }
+    // Fallback: shouldn't normally reach here
+    PluginEntry e;
+    e.name = name;
+    e.desc = desc;
+    e.path = eng->current_plugin_name();
+    plugins.push_back(std::move(e));
+    return 0;
+}
+
+int l_register_menu_item(lua_State* L) {
+    auto* eng = get_engine(L);
+    if (!eng) return 0;
+
+    const char* label = luaL_checkstring(L, 1);
+    luaL_checktype(L, 2, LUA_TFUNCTION);
+    lua_pushvalue(L, 2);
+    int ref = luaL_ref(L, LUA_REGISTRYINDEX);
+
+    auto& plugins = const_cast<std::vector<PluginEntry>&>(eng->plugins());
+    // Add to the most recently active plugin
+    for (auto it = plugins.rbegin(); it != plugins.rend(); ++it) {
+        if (it->path == eng->current_plugin_name()) {
+            it->items.push_back({label, ref});
+            return 0;
+        }
+    }
+    // If no plugin registered yet, attach to a default entry
+    if (!plugins.empty()) {
+        plugins.back().items.push_back({label, ref});
+    }
+    return 0;
+}
+
+int l_register_hotkey(lua_State* L) {
+    auto* eng = get_engine(L);
+    if (!eng) return 0;
+    const char* key_str = luaL_checkstring(L, 1);
+    luaL_checktype(L, 2, LUA_TFUNCTION);
+    lua_pushvalue(L, 2);
+    int ref = luaL_ref(L, LUA_REGISTRYINDEX);
+    eng->add_hotkey(key_str, ref);
+    return 0;
+}
+
+int l_register_on_analysis_complete(lua_State* L) {
+    auto* eng = get_engine(L);
+    if (!eng) return 0;
+    luaL_checktype(L, 1, LUA_TFUNCTION);
+    lua_pushvalue(L, 1);
+    int ref = luaL_ref(L, LUA_REGISTRYINDEX);
+    eng->add_analysis_cb(ref);
+    return 0;
+}
+
+} // anon namespace
+
+// -----------------------------------------------------------------------
+// LuaEngine implementation
+// -----------------------------------------------------------------------
 
 LuaEngine::LuaEngine() {
     L_ = luaL_newstate();
     luaL_openlibs(L_);
 }
 
 LuaEngine::~LuaEngine() {
+    // Release all Lua registry refs before closing
+    for (auto& p : plugins_)
+        for (auto& item : p.items)
+            if (item.cb_ref != LUA_NOREF) luaL_unref(L_, LUA_REGISTRYINDEX, item.cb_ref);
+    for (auto& [_, ref] : hotkeys_)
+        if (ref != LUA_NOREF) luaL_unref(L_, LUA_REGISTRYINDEX, ref);
+    for (auto ref : on_analysis_cbs_)
+        if (ref != LUA_NOREF) luaL_unref(L_, LUA_REGISTRYINDEX, ref);
     if (L_) lua_close(L_);
 }
 
 void LuaEngine::init(AnalysisDB* db, PEImage* img) {
-    db_ = db;
+    db_  = db;
     img_ = img;
     register_api();
 }
@@ -207,16 +368,147 @@ void LuaEngine::register_api() {
     lua_pushlightuserdata(L_, &nav_cb_);
     lua_setfield(L_, LUA_REGISTRYINDEX, "__hype_nav");
 
-    lua_register(L_, "get_name", l_get_name);
-    lua_register(L_, "set_name", l_set_name);
-    lua_register(L_, "get_func", l_get_func);
-    lua_register(L_, "get_insn", l_get_insn);
-    lua_register(L_, "get_bytes", l_get_bytes);
+    // Core API
+    lua_register(L_, "get_name",    l_get_name);
+    lua_register(L_, "set_name",    l_set_name);
+    lua_register(L_, "get_func",    l_get_func);
+    lua_register(L_, "get_insn",    l_get_insn);
+    lua_register(L_, "get_bytes",   l_get_bytes);
     lua_register(L_, "set_comment", l_set_comment);
     lua_register(L_, "get_xrefs_to", l_get_xrefs_to);
     lua_register(L_, "get_functions", l_get_functions);
-    lua_register(L_, "print", l_print);
-    lua_register(L_, "goto_addr", l_goto);
+    lua_register(L_, "print",       l_print);
+    lua_register(L_, "goto_addr",   l_goto);
+
+    // Plugin registration API
+    lua_register(L_, "register_plugin",               l_register_plugin);
+    lua_register(L_, "register_menu_item",            l_register_menu_item);
+    lua_register(L_, "register_hotkey",               l_register_hotkey);
+    lua_register(L_, "register_on_analysis_complete", l_register_on_analysis_complete);
+}
+
+// Register engine pointer and api before analysis (plugins load pre-loop).
+// We call register_api early so plugins can call register_* at load time
+// even though db_ and img_ are still null — API functions guard for null.
+void LuaEngine::load_plugins(const std::filesystem::path& dir) {
+    // Register the engine pointer early so register_* functions work
+    lua_pushlightuserdata(L_, this);
+    lua_setfield(L_, LUA_REGISTRYINDEX, "__hype_engine");
+    lua_pushlightuserdata(L_, &output_);
+    lua_setfield(L_, LUA_REGISTRYINDEX, "__hype_output");
+
+    // Register plugin API functions (safe even with null db_/img_)
+    lua_register(L_, "get_name",    l_get_name);
+    lua_register(L_, "set_name",    l_set_name);
+    lua_register(L_, "get_func",    l_get_func);
+    lua_register(L_, "get_insn",    l_get_insn);
+    lua_register(L_, "get_bytes",   l_get_bytes);
+    lua_register(L_, "set_comment", l_set_comment);
+    lua_register(L_, "get_xrefs_to", l_get_xrefs_to);
+    lua_register(L_, "get_functions", l_get_functions);
+    lua_register(L_, "print",       l_print);
+    lua_register(L_, "goto_addr",   l_goto);
+    lua_register(L_, "register_plugin",               l_register_plugin);
+    lua_register(L_, "register_menu_item",            l_register_menu_item);
+    lua_register(L_, "register_hotkey",               l_register_hotkey);
+    lua_register(L_, "register_on_analysis_complete", l_register_on_analysis_complete);
+
+    if (!std::filesystem::exists(dir) || !std::filesystem::is_directory(dir)) {
+        spdlog::info("lua_engine: plugins dir not found at {}", dir.string());
+        return;
+    }
+
+    // Collect and sort .lua files alphabetically
+    std::vector<std::filesystem::path> files;
+    for (auto& entry : std::filesystem::directory_iterator(dir)) {
+        if (entry.path().extension() == ".lua")
+            files.push_back(entry.path());
+    }
+    std::sort(files.begin(), files.end());
+
+    for (auto& fp : files) {
+        PluginEntry pe;
+        pe.path = fp.string();
+        pe.name = fp.stem().string(); // default name = filename stem
+        pe.desc = "";
+
+        current_plugin_ = pe.path;
+        plugins_.push_back(std::move(pe));
+
+        output_.clear();
+        int err = luaL_dofile(L_, fp.string().c_str());
+        if (err) {
+            const char* msg = lua_tostring(L_, -1);
+            plugins_.back().error     = true;
+            plugins_.back().error_msg = msg ? msg : "unknown error";
+            lua_pop(L_, 1);
+            spdlog::warn("lua_engine: plugin error [{}]: {}", fp.filename().string(), plugins_.back().error_msg);
+        } else {
+            spdlog::info("lua_engine: loaded plugin [{}] -> \"{}\"",
+                fp.filename().string(), plugins_.back().name);
+        }
+    }
+
+    spdlog::info("lua_engine: {} plugin(s) loaded from {}", plugins_.size(), dir.string());
+}
+
+void LuaEngine::invoke_menu_item(int plugin_idx, int item_idx) {
+    if (plugin_idx < 0 || plugin_idx >= static_cast<int>(plugins_.size())) return;
+    auto& plugin = plugins_[static_cast<size_t>(plugin_idx)];
+    if (item_idx < 0 || item_idx >= static_cast<int>(plugin.items.size())) return;
+    int ref = plugin.items[static_cast<size_t>(item_idx)].cb_ref;
+    if (ref == LUA_NOREF) return;
+
+    output_.clear();
+    lua_rawgeti(L_, LUA_REGISTRYINDEX, ref);
+    int err = lua_pcall(L_, 0, 0, 0);
+    if (err) {
+        const char* msg = lua_tostring(L_, -1);
+        output_ += std::string("[plugin error] ") + (msg ? msg : "unknown") + "\n";
+        lua_pop(L_, 1);
+    }
+    // output_ is forwarded to the Script Console by scriptc_ which reads it via execute()
+    // For plugin callbacks we flush directly via the output panel pointer stored in registry
+    lua_getfield(L_, LUA_REGISTRYINDEX, "__hype_output");
+    auto* out_ptr = static_cast<std::string*>(lua_touserdata(L_, -1));
+    lua_pop(L_, 1);
+    if (out_ptr && out_ptr != &output_) {
+        *out_ptr += output_;
+    }
+}
+
+void LuaEngine::run_analysis_complete_callbacks() {
+    for (int ref : on_analysis_cbs_) {
+        if (ref == LUA_NOREF) continue;
+        output_.clear();
+        lua_rawgeti(L_, LUA_REGISTRYINDEX, ref);
+        int err = lua_pcall(L_, 0, 0, 0);
+        if (err) {
+            const char* msg = lua_tostring(L_, -1);
+            spdlog::warn("lua_engine: on_analysis_complete callback error: {}",
+                msg ? msg : "unknown");
+            lua_pop(L_, 1);
+        }
+    }
+}
+
+void LuaEngine::check_hotkeys() {
+    auto& io = ImGui::GetIO();
+    if (io.WantTextInput) return;
+    for (auto& [key_str, ref] : hotkeys_) {
+        if (ref == LUA_NOREF) continue;
+        auto spec = parse_hotkey(key_str);
+        if (!check_hotkey(spec)) continue;
+
+        output_.clear();
+        lua_rawgeti(L_, LUA_REGISTRYINDEX, ref);
+        int err = lua_pcall(L_, 0, 0, 0);
+        if (err) {
+            const char* msg = lua_tostring(L_, -1);
+            spdlog::warn("lua_engine: hotkey callback error: {}", msg ? msg : "unknown");
+            lua_pop(L_, 1);
+        }
+    }
 }
 
 std::string LuaEngine::execute(const std::string& code) {
@@ -231,4 +523,4 @@ std::string LuaEngine::execute(const std::string& code) {
     return output_;
 }
 
-}
+} // namespace hype