@manybot/manybot 5.7.0 → 5.8.0

package/dist/kernel/commandAccess.js

@@ -0,0 +1,66 @@
+/**
+ * kernel/commandAccess.ts
+ *
+ * ctx.commands — read-only registry queries exposed to plugins (Phase 2
+ * of MANYBOT-6.md). Lets a plugin check whether another command exists,
+ * or read its desc/manual, without ctx.plugins.require()'ing the owning
+ * plugin. Primary consumer: many-ai, so it can verify a command before
+ * mentioning it instead of hallucinating.
+ *
+ * Lookups are case-sensitive and unaliased-vs-aliased the same way
+ * resolveDispatch() and the menu-alias check in commandRegistry.ts are —
+ * keyed exactly as the command/alias was declared, no implicit
+ * lowercasing here.
+ */
+import { getCommandRegistry } from "./commandRegistry.js";
+import { resolveLocalizedString } from "./commandMenu.js";
+/**
+ * All lookups take an optional explicit `registry` (defaulting to the
+ * live singleton via `getCommandRegistry()`) so this module can be unit
+ * tested with `buildCommandRegistry(...)` directly, the same convention
+ * `commandMenu.ts`'s `renderOverview(registry, lang)` uses.
+ */
+function resolveEntry(registry, invocation) {
+    if (!registry)
+        return null;
+    const id = registry.byInvocation.get(invocation);
+    if (!id)
+        return null;
+    return registry.byId.get(id) ?? null;
+}
+/** Whether `invocation` (a cmd or alias) resolves to a registered command. */
+export function exists(invocation, registry = getCommandRegistry()) {
+    return resolveEntry(registry, invocation) !== null;
+}
+/** Localized short description for `invocation`, or null if unknown/unset. */
+export function desc(invocation, lang, registry = getCommandRegistry()) {
+    const entry = resolveEntry(registry, invocation);
+    if (!entry)
+        return null;
+    return resolveLocalizedString(entry.desc, lang);
+}
+/** Localized manual text for `invocation`, falling back to `desc`. */
+export function manual(invocation, lang, registry = getCommandRegistry()) {
+    const entry = resolveEntry(registry, invocation);
+    if (!entry)
+        return null;
+    return resolveLocalizedString(entry.manual, lang) ?? resolveLocalizedString(entry.desc, lang);
+}
+/** All registered top-level commands, one entry per stable id. */
+export function list(lang, registry = getCommandRegistry()) {
+    if (!registry)
+        return [];
+    return Array.from(registry.byId.values(), (entry) => ({
+        id: entry.id,
+        cmd: entry.cmd,
+        aliases: [...entry.aliases],
+        category: entry.category,
+        desc: resolveLocalizedString(entry.desc, lang),
+    }));
+}
+/** Whether `text` is one of the menu command's own aliases (e.g. "menu", "help"). */
+export function isMenuAlias(text, registry = getCommandRegistry()) {
+    if (!registry)
+        return false;
+    return registry.menuAliases.has(text);
+}

package/dist/kernel/commandAccess.test.js

@@ -0,0 +1,74 @@
+import test, { describe } from "node:test";
+import assert from "node:assert/strict";
+import { exists, desc, manual, list, isMenuAlias } from "#kernel/commandAccess.js";
+import { buildCommandRegistry } from "#kernel/commandRegistry.js";
+function createTestRegistry() {
+    const plugins = new Map([
+        [
+            "utilPlugin",
+            {
+                name: "utilPlugin",
+                status: "active",
+                manifest: { name: "utilPlugin", version: "1.0.0" },
+                commands: {
+                    pingFn: {
+                        cmd: "ping",
+                        aliases: ["p"],
+                        desc: { pt: "Testa a latência", en: "Tests latency" },
+                        category: "utils",
+                        manual: "Uso: !ping",
+                    },
+                    infoFn: {
+                        cmd: "info",
+                        aliases: [],
+                        desc: "Informações do bot",
+                        category: "utils",
+                    },
+                },
+            },
+        ],
+    ]);
+    const categories = {
+        utils: { label: { pt: "Utilitários", en: "Utilities" }, order: 1 },
+    };
+    return buildCommandRegistry(null, plugins, undefined, undefined, categories);
+}
+describe("kernel/commandAccess", () => {
+    test("exists() is true for cmd and alias, false for unknown", () => {
+        const registry = createTestRegistry();
+        assert.equal(exists("ping", registry), true);
+        assert.equal(exists("p", registry), true);
+        assert.equal(exists("nope", registry), false);
+    });
+    test("exists() returns false with no registry", () => {
+        assert.equal(exists("ping", null), false);
+    });
+    test("desc() resolves the localized string for the requested lang", () => {
+        const registry = createTestRegistry();
+        assert.equal(desc("ping", "pt", registry), "Testa a latência");
+        assert.equal(desc("ping", "en", registry), "Tests latency");
+        assert.equal(desc("info", "pt", registry), "Informações do bot");
+        assert.equal(desc("nope", "pt", registry), null);
+    });
+    test("manual() falls back to desc() when no manual is set", () => {
+        const registry = createTestRegistry();
+        assert.equal(manual("ping", "pt", registry), "Uso: !ping");
+        assert.equal(manual("info", "pt", registry), "Informações do bot");
+    });
+    test("list() returns one entry per command with resolved desc", () => {
+        const registry = createTestRegistry();
+        const items = list("pt", registry);
+        assert.equal(items.length, 2);
+        const ping = items.find((i) => i.cmd === "ping");
+        assert.ok(ping);
+        assert.deepEqual(ping?.aliases, ["p"]);
+        assert.equal(ping?.category, "utils");
+        assert.equal(ping?.desc, "Testa a latência");
+    });
+    test("isMenuAlias() checks the registry's menuAliases set", () => {
+        const registry = createTestRegistry();
+        assert.equal(isMenuAlias("help", registry), true);
+        assert.equal(isMenuAlias("menu", registry), true);
+        assert.equal(isMenuAlias("ping", registry), false);
+    });
+});

package/dist/kernel/commandDeprecation.js

@@ -0,0 +1,168 @@
+/**
+ * commandDeprecation.ts
+ *
+ * Tracks command cmd/alias rename and removal across registry rebuilds.
+ * Persists state in the same SQLite database used by settingsDb.ts (separate
+ * file-scope DatabaseSync handle — same DB_PATH is fine).
+ *
+ * Two tables:
+ *   command_cmd_history      — current known (id → cmd). Populated on every
+ *                              syncCommandHistory() call; first-time inserts
+ *                              are silent (no deprecation triggered).
+ *   command_deprecations     — old_cmd → deprecation row. Created on rename
+ *                              or removal; expires by `notify_until`.
+ *
+ * Lookup is by old_cmd text — expired rows are treated as absent (lazy
+ * filtering, no cleanup sweep here).
+ */
+import { DatabaseSync } from "node:sqlite";
+import path from "path";
+import { mkdirSync } from "fs";
+import { logger } from "#logger";
+import { t } from "#i18n";
+import { CONFIG_DIR } from "#config";
+const DB_PATH = process.env.NODE_ENV === "test" ? ":memory:" : path.join(CONFIG_DIR, "settings.db");
+if (DB_PATH !== ":memory:") {
+    mkdirSync(path.dirname(DB_PATH), { recursive: true });
+}
+const db = new DatabaseSync(DB_PATH);
+db.exec("PRAGMA journal_mode = WAL");
+db.exec(`
+  CREATE TABLE IF NOT EXISTS command_cmd_history (
+    id         TEXT PRIMARY KEY,
+    cmd        TEXT NOT NULL,
+    updated_at INTEGER NOT NULL DEFAULT (unixepoch())
+  );
+
+  CREATE TABLE IF NOT EXISTS command_deprecations (
+    old_cmd     TEXT PRIMARY KEY,
+    id          TEXT NOT NULL,
+    new_cmd     TEXT,
+    notify_until INTEGER NOT NULL,
+    message     TEXT
+  );
+`);
+const stmts = {
+    getHistoryCmd: db.prepare("SELECT cmd FROM command_cmd_history WHERE id = ?"),
+    insertHistory: db.prepare(`
+    INSERT INTO command_cmd_history (id, cmd, updated_at)
+    VALUES (?, ?, unixepoch())
+    ON CONFLICT (id)
+    DO UPDATE SET cmd = excluded.cmd, updated_at = excluded.updated_at
+  `),
+    deleteHistory: db.prepare("DELETE FROM command_cmd_history WHERE id = ?"),
+    allHistoryIds: db.prepare("SELECT id FROM command_cmd_history"),
+    getDeprecation: db.prepare("SELECT old_cmd, id, new_cmd, notify_until, message FROM command_deprecations WHERE old_cmd = ?"),
+    upsertDeprecation: db.prepare(`
+    INSERT INTO command_deprecations (old_cmd, id, new_cmd, notify_until, message)
+    VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT (old_cmd)
+    DO UPDATE SET id = excluded.id,
+                  new_cmd = excluded.new_cmd,
+                  notify_until = excluded.notify_until,
+                  message = excluded.message
+  `),
+};
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/**
+ * Reconcile the current registry `byId` against the persisted history.
+ *
+ * Per id:
+ *   - not in history → INSERT silently (first sighting, no notice).
+ *   - in history, same cmd → no-op.
+ *   - in history, different cmd → INSERT into command_deprecations with the
+ *     OLD cmd, new_cmd = new cmd, notify_until = now + period.
+ *
+ * Ids that vanished from byId → INSERT into command_deprecations with
+ * new_cmd = null, and DELETE the history row (the deprecation IS the record
+ * that the id is gone).
+ *
+ * `spec.notifyChanges ?? defaults.notifyChanges` controls whether any row
+ * is written for that id. When false, the history is still updated silently
+ * and no deprecation is recorded (admin-opt-out).
+ */
+export function syncCommandHistory(byId, defaults, specs) {
+    const specById = new Map(specs.map(s => [s.id, s]));
+    const now = Date.now();
+    for (const [id, entry] of byId) {
+        const spec = specById.get(id);
+        const notify = spec?.notifyChanges ?? defaults.notifyChanges;
+        const existing = stmts.getHistoryCmd.get(id);
+        const prevCmd = existing?.cmd ?? null;
+        if (prevCmd === null) {
+            stmts.insertHistory.run(id, entry.cmd);
+            continue;
+        }
+        if (prevCmd === entry.cmd)
+            continue;
+        if (notify) {
+            const periodMs = defaults.notifyPeriodDays * MS_PER_DAY;
+            stmts.upsertDeprecation.run(prevCmd, id, entry.cmd, now + periodMs, spec?.deprecatedMessage ?? null);
+            logger.warn(t("system.commandDeprecationRenamed", {
+                id,
+                old: prevCmd,
+                new: entry.cmd
+            }));
+        }
+        stmts.insertHistory.run(id, entry.cmd);
+    }
+    const currentIds = new Set(byId.keys());
+    const persistedIds = stmts.allHistoryIds.all().map(r => r.id);
+    for (const id of persistedIds) {
+        if (currentIds.has(id))
+            continue;
+        const existing = stmts.getHistoryCmd.get(id);
+        if (!existing)
+            continue;
+        const spec = specById.get(id);
+        const notify = spec?.notifyChanges ?? defaults.notifyChanges;
+        if (notify) {
+            const periodMs = defaults.notifyPeriodDays * MS_PER_DAY;
+            stmts.upsertDeprecation.run(existing.cmd, id, null, now + periodMs, spec?.deprecatedMessage ?? null);
+            logger.warn(t("system.commandDeprecationRemoved", {
+                id,
+                old: existing.cmd
+            }));
+        }
+        stmts.deleteHistory.run(id);
+    }
+}
+/**
+ * Returns the active deprecation row for `cmdText`, or null if there is no
+ * deprecation or it has already expired.
+ */
+export function getActiveDeprecation(cmdText) {
+    const row = stmts.getDeprecation.get(cmdText);
+    if (!row)
+        return null;
+    if (row.notify_until <= Date.now())
+        return null;
+    return row;
+}
+function interpolate(template, vars) {
+    return template.replace(/\{\{(\w+)\}\}/g, (_match, name) => Object.prototype.hasOwnProperty.call(vars, name) ? vars[name] : `{{${name}}}`);
+}
+/**
+ * Resolve the final user-facing message:
+ *   1. row.message (per-command override from yaml `deprecatedMessage`)
+ *   2. defaults.notifyMessage (global override)
+ *   3. built-in fallback ("Command \"{old}\" was renamed to \"{new}\"..." or
+ *      "Command \"{old}\" has been removed" for removals)
+ */
+export function formatDeprecationMessage(row, defaults) {
+    const vars = {
+        old: row.old_cmd,
+        new: row.new_cmd ?? "",
+        days: String(Math.max(0, Math.ceil((row.notify_until - Date.now()) / MS_PER_DAY))),
+    };
+    if (row.message && row.message.trim().length > 0) {
+        return interpolate(row.message, vars);
+    }
+    if (defaults.notifyMessage && defaults.notifyMessage.trim().length > 0) {
+        return interpolate(defaults.notifyMessage, vars);
+    }
+    const fallbackKey = row.new_cmd === null
+        ? "system.commandDeprecationFallbackRemoved"
+        : "system.commandDeprecationFallbackRenamed";
+    return interpolate(t(fallbackKey), vars);
+}

package/dist/kernel/commandDeprecation.test.js

@@ -0,0 +1,107 @@
+import test, { describe } from "node:test";
+import assert from "node:assert/strict";
+import { syncCommandHistory, getActiveDeprecation, formatDeprecationMessage } from "#kernel/commandDeprecation.js";
+function createMockEntry(id, cmd) {
+    return {
+        id,
+        cmd,
+        aliases: [],
+        desc: null,
+        category: null,
+        group: null,
+        manual: null,
+        source: "plugin",
+        pluginName: "testPlugin",
+        function: null,
+        handler: null,
+        text: null,
+        permissions: {
+            admin: false,
+            botAdmin: false,
+            scope: "any",
+            owner: false,
+            cooldownSeconds: 0,
+            whitelist: null,
+            blacklist: null,
+            messages: {},
+        },
+        arguments: [],
+        subcommands: {},
+        categoryHiddenInScope: null,
+    };
+}
+describe("kernel/commandDeprecation", () => {
+    const defaults = {
+        notifyChanges: true,
+        notifyPeriodDays: 7,
+        notifyMessage: null,
+    };
+    test("silently inserts history on first sync", () => {
+        const byId = new Map([
+            ["plugin::cmd1", createMockEntry("plugin::cmd1", "oldname")],
+        ]);
+        syncCommandHistory(byId, defaults, []);
+        // First sighting should not create an active deprecation for oldname
+        assert.equal(getActiveDeprecation("oldname"), null);
+    });
+    test("records deprecation when command is renamed across syncs", () => {
+        const byId1 = new Map([
+            ["plugin::cmd1", createMockEntry("plugin::cmd1", "oldname")],
+        ]);
+        syncCommandHistory(byId1, defaults, []);
+        // Sync 2: cmd name changed to newname
+        const byId2 = new Map([
+            ["plugin::cmd1", createMockEntry("plugin::cmd1", "newname")],
+        ]);
+        syncCommandHistory(byId2, defaults, []);
+        const deprecation = getActiveDeprecation("oldname");
+        assert.ok(deprecation);
+        assert.equal(deprecation?.old_cmd, "oldname");
+        assert.equal(deprecation?.new_cmd, "newname");
+        const formatted = formatDeprecationMessage(deprecation, defaults);
+        assert.ok(formatted.length > 0);
+    });
+    test("records deprecation when command is removed from registry", () => {
+        const byId1 = new Map([
+            ["plugin::cmdRem", createMockEntry("plugin::cmdRem", "removedcmd")],
+        ]);
+        syncCommandHistory(byId1, defaults, []);
+        // Sync 2: command removed
+        const byId2 = new Map();
+        syncCommandHistory(byId2, defaults, []);
+        const deprecation = getActiveDeprecation("removedcmd");
+        assert.ok(deprecation);
+        assert.equal(deprecation?.old_cmd, "removedcmd");
+        assert.equal(deprecation?.new_cmd, null);
+    });
+    test("respects notifyChanges = false opt-out", () => {
+        const byId1 = new Map([
+            ["plugin::optOut", createMockEntry("plugin::optOut", "alpha")],
+        ]);
+        const specs1 = [{
+                id: "plugin::optOut",
+                plugin: "plugin",
+                function: "optOut",
+                cmd: "alpha",
+                aliases: [],
+                desc: null,
+                category: null,
+                group: null,
+                manual: null,
+                text: null,
+                deprecatedMessage: null,
+                notifyChanges: false,
+                permissions: null,
+                messages: null,
+                arguments: [],
+                subcommands: [],
+            }];
+        syncCommandHistory(byId1, defaults, specs1);
+        // Rename with notifyChanges = false
+        const byId2 = new Map([
+            ["plugin::optOut", createMockEntry("plugin::optOut", "beta")],
+        ]);
+        syncCommandHistory(byId2, defaults, specs1);
+        assert.equal(getActiveDeprecation("alpha"), null);
+    });
+});

package/dist/kernel/commandMenu.js

@@ -0,0 +1,268 @@
+/**
+ * commandMenu.ts
+ *
+ * Menu system for ManyBot (overview, category, manual, not-found).
+ */
+import { CMD_PREFIX } from "#config";
+import { getCurrentLang, tFor } from "#i18n";
+import { buildSettingsApi } from "./settingsDb.js";
+/**
+ * Checks if the user should be shown the welcome message,
+ * and marks them as seen if so.
+ */
+export function checkAndTriggerWelcomeMessage(userId, registry, lang) {
+    if (!registry.menu.welcomeMessage)
+        return null;
+    const settings = buildSettingsApi("kernel", userId);
+    const lastSeen = settings.get("last_welcome_seen");
+    const now = Math.floor(Date.now() / 1000);
+    const windowSeconds = (registry.menu.welcomeWindowDays || 3) * 86400;
+    if (!lastSeen || now - lastSeen > windowSeconds) {
+        settings.set("last_welcome_seen", now);
+        const rawMsg = resolveLocalizedString(registry.menu.welcomeMessage, lang);
+        if (!rawMsg)
+            return null;
+        return rawMsg.replace(/\{prefix\}/g, CMD_PREFIX);
+    }
+    return null;
+}
+/**
+ * Resolves a LocalizedString (string | Record<string, string>) to a single
+ * string for the requested language (or system language), falling back to
+ * English or the first available string.
+ */
+export function resolveLocalizedString(raw, lang) {
+    if (!raw)
+        return null;
+    if (typeof raw === "string")
+        return raw;
+    if (typeof raw === "object" && raw !== null) {
+        const targetLang = (lang || getCurrentLang()).toLowerCase();
+        if (typeof raw[targetLang] === "string")
+            return raw[targetLang];
+        if (typeof raw.en === "string")
+            return raw.en;
+        if (typeof raw.pt === "string")
+            return raw.pt;
+        if (typeof raw.es === "string")
+            return raw.es;
+        const values = Object.values(raw);
+        if (values.length > 0 && typeof values[0] === "string")
+            return values[0];
+    }
+    return null;
+}
+export function renderOverview(registry, lang, page, scope) {
+    const parts = [];
+    const titleStr = resolveLocalizedString(registry.menu.title, lang) ?? "🤖 ManyBot — Menu";
+    parts.push(`*${titleStr}*`);
+    const rawIntro = resolveLocalizedString(registry.menu.intro, lang) ??
+        tFor(lang, "menu.intro");
+    const introStr = rawIntro.replace(/\{prefix\}/g, CMD_PREFIX);
+    parts.push(introStr);
+    parts.push(""); // blank line before categories/commands
+    const allEntries = Array.from(registry.byId.values());
+    const categories = Object.entries(registry.categories);
+    const pageSize = registry.menu.pageSize ?? 15;
+    if (categories.length > 0) {
+        // Sort defined categories by order ascending
+        const sortedCategories = categories.sort((a, b) => a[1].order - b[1].order);
+        const assignedIds = new Set();
+        for (const [catKey, catConfig] of sortedCategories) {
+            if (scope && catConfig.scope && catConfig.scope !== scope) {
+                continue;
+            }
+            const entries = allEntries
+                .filter(e => e.category === catKey)
+                .filter(e => {
+                if (!scope)
+                    return true;
+                if (e.categoryHiddenInScope && e.categoryHiddenInScope === scope)
+                    return false;
+                return true;
+            })
+                .sort((a, b) => a.cmd.localeCompare(b.cmd));
+            if (entries.length === 0)
+                continue;
+            const catLabel = resolveLocalizedString(catConfig.label, lang) ?? catKey;
+            parts.push(`📁 *${catLabel}*`);
+            for (const entry of entries) {
+                assignedIds.add(entry.id);
+                const descStr = resolveLocalizedString(entry.desc, lang);
+                if (descStr) {
+                    parts.push(`  • ${CMD_PREFIX}${entry.cmd} — ${descStr}`);
+                }
+                else {
+                    parts.push(`  • ${CMD_PREFIX}${entry.cmd}`);
+                }
+            }
+            parts.push("");
+        }
+        // Uncategorized entries
+        const uncategorized = allEntries
+            .filter(e => !assignedIds.has(e.id))
+            .filter(e => {
+            if (!scope)
+                return true;
+            if (e.categoryHiddenInScope && e.categoryHiddenInScope === scope)
+                return false;
+            return true;
+        })
+            .sort((a, b) => a.cmd.localeCompare(b.cmd));
+        if (uncategorized.length > 0) {
+            const otherLabel = tFor(lang, "menu.other");
+            parts.push(`📁 *${otherLabel}*`);
+            for (const entry of uncategorized) {
+                const descStr = resolveLocalizedString(entry.desc, lang);
+                if (descStr) {
+                    parts.push(`  • ${CMD_PREFIX}${entry.cmd} — ${descStr}`);
+                }
+                else {
+                    parts.push(`  • ${CMD_PREFIX}${entry.cmd}`);
+                }
+            }
+            parts.push("");
+        }
+    }
+    else {
+        // Flat command list with pagination
+        const filteredEntries = allEntries.filter(e => {
+            if (!scope)
+                return true;
+            if (e.categoryHiddenInScope && e.categoryHiddenInScope === scope)
+                return false;
+            return true;
+        });
+        const startIdx = page ? (page - 1) * pageSize : 0;
+        const visibleEntries = filteredEntries.slice(startIdx, startIdx + pageSize);
+        for (const entry of visibleEntries) {
+            const descStr = resolveLocalizedString(entry.desc, lang);
+            if (descStr) {
+                parts.push(`• ${CMD_PREFIX}${entry.cmd} — ${descStr}`);
+            }
+            else {
+                parts.push(`• ${CMD_PREFIX}${entry.cmd}`);
+            }
+        }
+        parts.push("");
+    }
+    const footerStr = resolveLocalizedString(registry.menu.footer, lang);
+    if (footerStr) {
+        parts.push(footerStr.replace(/\{prefix\}/g, CMD_PREFIX));
+    }
+    return parts.join("\n").trim();
+}
+export function renderCategory(registry, categoryKey, lang, scope) {
+    const normTarget = categoryKey.trim().toLowerCase();
+    // Match category key or category label
+    let matchedKey = null;
+    let matchedLabel = null;
+    for (const [catKey, catConfig] of Object.entries(registry.categories)) {
+        if (scope && catConfig.scope && catConfig.scope !== scope) {
+            continue;
+        }
+        const labelStr = resolveLocalizedString(catConfig.label, lang) ?? catKey;
+        if (catKey.toLowerCase() === normTarget || labelStr.toLowerCase() === normTarget) {
+            matchedKey = catKey;
+            matchedLabel = labelStr;
+            break;
+        }
+    }
+    if (!matchedKey) {
+        // Try matching if any command has entry.category === categoryKey
+        const hasCategoryInEntries = Array.from(registry.byId.values()).some(e => e.category?.toLowerCase() === normTarget);
+        if (hasCategoryInEntries) {
+            matchedKey = categoryKey;
+            matchedLabel = categoryKey;
+        }
+        else {
+            return null; // Category not found
+        }
+    }
+    // If we have a scope and the matched category has a scope that doesn't match, return null
+    if (scope && matchedKey && registry.categories[matchedKey]?.scope && registry.categories[matchedKey].scope !== scope) {
+        return null;
+    }
+    const entries = Array.from(registry.byId.values())
+        .filter(e => e.category?.toLowerCase() === matchedKey.toLowerCase())
+        .filter(e => {
+        if (!scope)
+            return true;
+        // If entry has a specific scope defined and it doesn't match the requested scope, exclude it
+        if (e.categoryHiddenInScope && e.categoryHiddenInScope === scope)
+            return false;
+        return true;
+    })
+        .sort((a, b) => a.cmd.localeCompare(b.cmd));
+    if (entries.length === 0)
+        return null;
+    const parts = [];
+    parts.push(`📁 *${tFor(lang, "menu.category")}: ${matchedLabel}*`);
+    parts.push("");
+    for (const entry of entries) {
+        const descStr = resolveLocalizedString(entry.desc, lang);
+        if (descStr) {
+            parts.push(`• ${CMD_PREFIX}${entry.cmd} — ${descStr}`);
+        }
+        else {
+            parts.push(`• ${CMD_PREFIX}${entry.cmd}`);
+        }
+    }
+    return parts.join("\\n").trim();
+}
+export function renderManual(entry, registry, lang) {
+    const parts = [];
+    parts.push(`📖 *${tFor(lang, "menu.manual")}: ${CMD_PREFIX}${entry.cmd}*`);
+    if (entry.aliases.length > 0) {
+        parts.push(`*Aliases:* ${entry.aliases.map(a => CMD_PREFIX + a).join(", ")}`);
+    }
+    if (entry.category && registry.categories[entry.category]) {
+        const catLabel = resolveLocalizedString(registry.categories[entry.category].label, lang) ?? entry.category;
+        parts.push(`*${tFor(lang, "menu.category")}:* ${catLabel}`);
+    }
+    parts.push("");
+    const descStr = resolveLocalizedString(entry.desc, lang);
+    if (descStr) {
+        parts.push(`*${tFor(lang, "menu.description")}:* ${descStr}`);
+        parts.push("");
+    }
+    const manualStr = resolveLocalizedString(entry.manual, lang);
+    if (manualStr) {
+        parts.push(manualStr);
+    }
+    else {
+        parts.push(tFor(lang, "system.commandManualMissing", { cmd: entry.cmd }));
+    }
+    return parts.join("\n").trim();
+}
+export function renderNotFound(invocation, registry, lang) {
+    const menuCmd = registry.menu.cmd;
+    return tFor(lang, "system.commandNotFound", { cmd: invocation, prefix: CMD_PREFIX, menuCmd });
+}
+export function handleMenuCommand(command, rawArgs, registry, lang, scope) {
+    const trimmed = rawArgs.trim();
+    if (!trimmed) {
+        return renderOverview(registry, lang, undefined, scope);
+    }
+    // Check if rawArgs is a page number or starts with "page <number>"
+    const pageMatch = trimmed.match(/^(?:page\s+)?(\d+)$/i);
+    if (pageMatch) {
+        const pageNum = parseInt(pageMatch[1], 10);
+        return renderOverview(registry, lang, pageNum, scope);
+    }
+    const arg1 = trimmed.split(/\s+/)[0].toLowerCase();
+    const cleanArg = arg1.startsWith(CMD_PREFIX) ? arg1.slice(CMD_PREFIX.length) : arg1;
+    // 1. Match category
+    const categoryResult = renderCategory(registry, cleanArg, lang, scope);
+    if (categoryResult) {
+        return categoryResult;
+    }
+    // 2. Match command entry
+    const entryId = registry.byInvocation.get(cleanArg);
+    const entry = entryId ? registry.byId.get(entryId) : null;
+    if (entry) {
+        return renderManual(entry, registry, lang);
+    }
+    // 3. Fallback not-found
+    return renderNotFound(cleanArg, registry, lang);
+}