@manybot/manybot 5.8.0 → 5.9.0

package/dist/kernel/commandPermissions.test.js

@@ -2,11 +2,14 @@ import test, { describe } from "node:test";
 import assert from "node:assert/strict";
 import { checkPermission, clearCooldowns, matchId, matchesAny } from "./commandPermissions.js";
 import { resolvePermissions } from "./commandRegistry.js";
+function senderOf(pn) {
+    return { lid: null, pn };
+}
 function createMockContext(overrides) {
     return {
         isGroup: false,
         chatId: "123456789@c.us",
-        senderId: "5511999999999@c.us",
+        sender: senderOf("5511999999999@c.us"),
         isSenderAdmin: async () => false,
         isBotAdmin: async () => false,
         ...overrides,
@@ -25,12 +28,15 @@ function createMockEntry(specPerms, specMsgs, pluginPerms, defaultsPerms, defaul
         source: "plugin",
         pluginName: "testPlugin",
         function: null,
+        functions: [],
+        loading: null,
         handler: async () => "ok",
         text: null,
         permissions,
         arguments: [],
         subcommands: {},
         categoryHiddenInScope: null,
+        hiddenOutsideScope: null,
     };
 }
 describe("commandPermissions", () => {
@@ -51,7 +57,7 @@ describe("commandPermissions", () => {
     });
     test("owner permission check", async () => {
         const ownerEntry = createMockEntry({ owner: true }, { ownerOnly: "Only owner allowed" });
-        const nonOwnerCtx = createMockContext({ senderId: "5511888888888@c.us" });
+        const nonOwnerCtx = createMockContext({ sender: senderOf("5511888888888@c.us") });
         // When OWNER_NUMBER is not set or sender does not match
         const res = await checkPermission(ownerEntry, nonOwnerCtx);
         assert.equal(res.allowed, false);
@@ -76,6 +82,38 @@ describe("commandPermissions", () => {
         const res4 = await checkPermission(dmEntry, dmCtx);
         assert.equal(res4.allowed, true);
     });
+    test("dono permission check (specific-owner JID, independent of OWNER_NUMBER)", async () => {
+        const donoEntry = createMockEntry({ dono: "5511999999999@c.us" }, { donoOnly: "Only the dono can use this" });
+        const nonDonoCtx = createMockContext({ sender: senderOf("5511888888888@c.us") });
+        const res1 = await checkPermission(donoEntry, nonDonoCtx);
+        assert.equal(res1.allowed, false);
+        if (!res1.allowed)
+            assert.equal(res1.message, "Only the dono can use this");
+        const donoCtx = createMockContext({ sender: senderOf("5511999999999@c.us") });
+        const res2 = await checkPermission(donoEntry, donoCtx);
+        assert.equal(res2.allowed, true);
+    });
+    test("dono check accepts either LID or PN form of the sender", async () => {
+        const donoEntry = createMockEntry({ dono: "5511999999999" });
+        const lidOnlyCtx = createMockContext({ sender: { lid: "5511999999999@lid", pn: null } });
+        assert.equal((await checkPermission(donoEntry, lidOnlyCtx)).allowed, true);
+    });
+    test("allowedChats check (closed list of chats the command may run in)", async () => {
+        const entry = createMockEntry({ allowedChats: ["120363111111111111@g.us"] }, { allowedChats: "This command doesn't run here" });
+        const allowedCtx = createMockContext({ isGroup: true, chatId: "120363111111111111@g.us" });
+        const disallowedCtx = createMockContext({ isGroup: true, chatId: "120363999999999999@g.us" });
+        const resAllowed = await checkPermission(entry, allowedCtx);
+        assert.equal(resAllowed.allowed, true);
+        const resDisallowed = await checkPermission(entry, disallowedCtx);
+        assert.equal(resDisallowed.allowed, false);
+        if (!resDisallowed.allowed)
+            assert.equal(resDisallowed.message, "This command doesn't run here");
+    });
+    test("allowedChats check is skipped entirely when the list is empty/unset", async () => {
+        const entry = createMockEntry({ allowedChats: [] });
+        const anyChatCtx = createMockContext({ isGroup: true, chatId: "120363000000000000@g.us" });
+        assert.equal((await checkPermission(entry, anyChatCtx)).allowed, true);
+    });
     test("blacklist check", async () => {
         const entry = createMockEntry({
             blacklist: {
@@ -83,9 +121,9 @@ describe("commandPermissions", () => {
                 users: ["5511888888888@c.us"],
             },
         });
-        const blacklistedUserCtx = createMockContext({ senderId: "5511888888888@c.us" });
+        const blacklistedUserCtx = createMockContext({ sender: senderOf("5511888888888@c.us") });
         const blacklistedGroupCtx = createMockContext({ isGroup: true, chatId: "120363999999999999@g.us" });
-        const allowedCtx = createMockContext({ senderId: "5511999999999@c.us" });
+        const allowedCtx = createMockContext({ sender: senderOf("5511999999999@c.us") });
         assert.equal((await checkPermission(entry, blacklistedUserCtx)).allowed, false);
         assert.equal((await checkPermission(entry, blacklistedGroupCtx)).allowed, false);
         assert.equal((await checkPermission(entry, allowedCtx)).allowed, true);
@@ -97,14 +135,14 @@ describe("commandPermissions", () => {
                 users: ["5511999999999@c.us"],
             },
         });
-        const whitelistedUserCtx = createMockContext({ senderId: "5511999999999@c.us" });
-        const unwhitelistedUserCtx = createMockContext({ senderId: "5511888888888@c.us" });
+        const whitelistedUserCtx = createMockContext({ sender: senderOf("5511999999999@c.us") });
+        const unwhitelistedUserCtx = createMockContext({ sender: senderOf("5511888888888@c.us") });
         assert.equal((await checkPermission(entry, whitelistedUserCtx)).allowed, true);
         assert.equal((await checkPermission(entry, unwhitelistedUserCtx)).allowed, false);
     });
     test("admin and botAdmin checks", async () => {
-        const adminEntry = createMockEntry({ admin: true }, { senderNotAdmin: "Need admin" });
-        const botAdminEntry = createMockEntry({ botAdmin: true }, { botNotAdmin: "Need bot admin" });
+        const adminEntry = createMockEntry({ admin: true }, { senderNotAdmin: "Need admin", wrongScope: "Group required" });
+        const botAdminEntry = createMockEntry({ botAdmin: true }, { botNotAdmin: "Need bot admin", wrongScope: "Group required" });
         const nonAdminGroupCtx = createMockContext({
             isGroup: true,
             isSenderAdmin: async () => false,
@@ -124,12 +162,24 @@ describe("commandPermissions", () => {
         if (!resBotAdmin.allowed)
             assert.equal(resBotAdmin.message, "Need bot admin");
         assert.equal((await checkPermission(adminEntry, adminGroupCtx)).allowed, true);
+        // Outside a group there's no admin concept at all — this must be
+        // reported as wrongScope, not as "you/the bot aren't admin", since
+        // isSenderAdmin()/isBotAdmin() are never even called here.
+        const dmCtx = createMockContext({ isGroup: false });
+        const resAdminDm = await checkPermission(adminEntry, dmCtx);
+        assert.equal(resAdminDm.allowed, false);
+        if (!resAdminDm.allowed)
+            assert.equal(resAdminDm.message, "Group required");
+        const resBotAdminDm = await checkPermission(botAdminEntry, dmCtx);
+        assert.equal(resBotAdminDm.allowed, false);
+        if (!resBotAdminDm.allowed)
+            assert.equal(resBotAdminDm.message, "Group required");
         assert.equal((await checkPermission(botAdminEntry, adminGroupCtx)).allowed, true);
     });
     test("cooldown check and state consumption", async () => {
         clearCooldowns();
         const entry = createMockEntry({ cooldownSeconds: 30 }, { cooldown: "Wait {{seconds}}s" });
-        const ctx = createMockContext({ senderId: "5511999999999@c.us" });
+        const ctx = createMockContext({ sender: senderOf("5511999999999@c.us") });
         // First invocation passes and sets cooldown
         const res1 = await checkPermission(entry, ctx);
         assert.equal(res1.allowed, true);
@@ -144,6 +194,24 @@ describe("commandPermissions", () => {
         const res3 = await checkPermission(entry, ctx);
         assert.equal(res3.allowed, true);
     });
+    test("evaluation order: dono is checked before allowedChats/blacklist", async () => {
+        const entry = createMockEntry({
+            dono: "5511999999999@c.us",
+            allowedChats: ["120363111111111111@g.us"],
+            blacklist: { groups: [], users: ["5511888888888@c.us"] },
+        }, { donoOnly: "dono message", allowedChats: "chats message", blacklist: "blacklist message" });
+        // Sender fails dono AND would also fail allowedChats/blacklist — dono's
+        // message must win since it's evaluated first.
+        const ctx = createMockContext({
+            sender: senderOf("5511888888888@c.us"),
+            isGroup: true,
+            chatId: "120363999999999999@g.us",
+        });
+        const res = await checkPermission(entry, ctx);
+        assert.equal(res.allowed, false);
+        if (!res.allowed)
+            assert.equal(res.message, "dono message");
+    });
     test("cooldown is NOT consumed when an earlier check fails", async () => {
         clearCooldowns();
         const entry = createMockEntry({ scope: "group", cooldownSeconds: 30 }, { wrongScope: "Group only" });

package/dist/kernel/commandRegistry.js

@@ -12,12 +12,16 @@ import { t } from "#i18n";
 import { loadCommandsConfig, } from "./commandsConfig.js";
 import { pluginRegistry, resolvePluginCommandHandler, } from "./pluginLoader.js";
 import { getActiveDeprecation, syncCommandHistory } from "./commandDeprecation.js";
+import { resolveCoreCommandHandler } from "./coreCommands.js";
 export const DEFAULT_PERMISSION_MESSAGES = {
     botNotAdmin: () => t("commandPermissions.botNotAdmin"),
     senderNotAdmin: () => t("commandPermissions.senderNotAdmin"),
     ownerOnly: () => t("commandPermissions.ownerOnly"),
+    donoOnly: () => t("commandPermissions.donoOnly"),
     wrongScope: () => t("commandPermissions.wrongScope"),
     cooldown: () => t("commandPermissions.cooldown"),
+    blacklist: () => t("commandPermissions.blacklist"),
+    allowedChats: () => t("commandPermissions.allowedChats"),
 };
 export function resolvePermissions(specPerms, specMsgs, pluginPerms, defaultsPerms, defaultsMsgs, fallbackScope) {
     const admin = specPerms?.admin ?? pluginPerms?.admin ?? false;
@@ -25,6 +29,33 @@ export function resolvePermissions(specPerms, specMsgs, pluginPerms, defaultsPer
     const scope = specPerms?.scope ?? pluginPerms?.scope ?? fallbackScope ?? "any";
     const owner = specPerms?.owner ?? pluginPerms?.owner ?? false;
     const cooldownSeconds = specPerms?.cooldownSeconds ?? pluginPerms?.cooldownSeconds ?? defaultsPerms?.cooldownSeconds ?? 0;
+    // `dono` is YAML-only (no plugin-level equivalent). Per-spec dono
+    // wins; falls back to null = "no specific owner restriction" (the
+    // global OWNER_NUMBER in manybot.toml is independent).
+    const dono = specPerms?.dono ?? null;
+    // `allowed_chats:` is a closed list of JIDs the command may run in.
+    // Only set by the YAML spec; null = no chat restriction.
+    const allowedChats = specPerms?.allowedChats && specPerms.allowedChats.length > 0
+        ? [...specPerms.allowedChats]
+        : null;
+    // `hidden_outside_scope:` mirrors `group_only` / `dm_only`. Compute it
+    // here so the resolved value is consistent across the menu and the
+    // permission check. spec wins over plugin: a plugin manifest that
+    // declares `group_only: true` is hidden from DMs unless the spec
+    // narrows it differently.
+    let hiddenOutsideScope = null;
+    const scopeSrc = specPerms?.scope ?? pluginPerms?.scope ?? null;
+    const hiddenFlag = specPerms?.hiddenOutsideScope ?? pluginPerms?.hiddenOutsideScope ?? false;
+    const groupOnlyFlag = specPerms?.groupOnly ?? pluginPerms?.groupOnly ?? false;
+    const dmOnlyFlag = specPerms?.dmOnly ?? pluginPerms?.dmOnly ?? false;
+    if (scopeSrc === "group")
+        hiddenOutsideScope = "group";
+    else if (scopeSrc === "dm")
+        hiddenOutsideScope = "dm";
+    else if (hiddenFlag === true || groupOnlyFlag === true)
+        hiddenOutsideScope = "group";
+    else if (dmOnlyFlag === true)
+        hiddenOutsideScope = "dm";
     const rawWhitelist = specPerms?.whitelist ?? pluginPerms?.whitelist ?? defaultsPerms?.whitelist ?? null;
     const rawBlacklist = specPerms?.blacklist ?? pluginPerms?.blacklist ?? defaultsPerms?.blacklist ?? null;
     const whitelist = rawWhitelist
@@ -43,8 +74,11 @@ export function resolvePermissions(specPerms, specMsgs, pluginPerms, defaultsPer
         botNotAdmin: specMsgs?.botNotAdmin ?? defaultsMsgs?.botNotAdmin ?? DEFAULT_PERMISSION_MESSAGES.botNotAdmin(),
         senderNotAdmin: specMsgs?.senderNotAdmin ?? defaultsMsgs?.senderNotAdmin ?? DEFAULT_PERMISSION_MESSAGES.senderNotAdmin(),
         ownerOnly: specMsgs?.ownerOnly ?? defaultsMsgs?.ownerOnly ?? undefined,
+        donoOnly: specMsgs?.donoOnly ?? defaultsMsgs?.donoOnly ?? DEFAULT_PERMISSION_MESSAGES.donoOnly(),
         wrongScope: specMsgs?.wrongScope ?? defaultsMsgs?.wrongScope ?? DEFAULT_PERMISSION_MESSAGES.wrongScope(),
         cooldown: specMsgs?.cooldown ?? defaultsMsgs?.cooldown ?? DEFAULT_PERMISSION_MESSAGES.cooldown(),
+        blacklist: specMsgs?.blacklist ?? defaultsMsgs?.blacklist ?? DEFAULT_PERMISSION_MESSAGES.blacklist(),
+        allowedChats: specMsgs?.allowedChats ?? defaultsMsgs?.allowedChats ?? DEFAULT_PERMISSION_MESSAGES.allowedChats(),
     };
     return {
         admin,
@@ -54,6 +88,9 @@ export function resolvePermissions(specPerms, specMsgs, pluginPerms, defaultsPer
         cooldownSeconds,
         whitelist,
         blacklist,
+        dono,
+        allowedChats,
+        hiddenOutsideScope,
         messages,
     };
 }
@@ -133,7 +170,7 @@ function registerInvocationWithDeprecationGuard(byInvocation, text, entryId, isO
         return registerInvocation(byInvocation, text, entryId, isOverride);
     }
     const deprecation = getActiveDeprecation(text);
-    if (deprecation) {
+    if (deprecation && deprecation.id !== entryId) {
         logger.warn(t("system.commandDeprecationReservedInvocation", {
             text,
             id: deprecation.id
@@ -142,7 +179,8 @@ function registerInvocationWithDeprecationGuard(byInvocation, text, entryId, isO
     }
     return registerInvocation(byInvocation, text, entryId, isOverride);
 }
-const DEFAULT_MENU_CONFIG = {
+export const DEFAULT_MENU_CONFIG = {
+    enabled: false,
     title: "🤖 ManyBot — Menu",
     intro: {
         en: "Use {prefix}<command> to run it or {prefix}help <command> to view its manual.",
@@ -153,6 +191,8 @@ const DEFAULT_MENU_CONFIG = {
     cmd: "menu",
     aliases: ["help", "man", "menu", "bot", "?"],
     notFoundFallback: false,
+    suggestSimilar: false,
+    suggestMaxDistance: 2,
     welcomeMessage: null,
     welcomeWindowDays: 3,
     pageSize: 15,
@@ -164,19 +204,25 @@ function resolveCategoryHiddenInScope(category, categories) {
 }
 /**
  * Resolve a `CommandSubcommandSpec` into the runtime `CommandSubcommand`.
- * The sub shares the parent's plugin handler function by default; if
- * `spec.function` is set, it overrides the parent's `function` field.
+ *
+ * Function-chain inheritance: a sub with `spec.functions === null` (no
+ * override) inherits the parent's resolved chain. With an explicit list
+ * (even an empty one) it uses that. The primary `function` is set to the
+ * first non-empty entry, falling back to the parent's primary. Same
+ * convention for `loading:` — spec override wins, otherwise the parent's
+ * resolved spec carries through.
+ *
  * Subcommand permissions inherit from the parent's resolved permissions
  * unless the spec overrides them — `parent.permissions.scope` is passed
  * as `fallbackScope` to close the category → command → subcommand chain.
  */
-function buildSubcommandFromSpec(spec, parent, pluginName, defaultsByKey, defaults, manuals) {
+function buildSubcommandFromSpec(spec, parent, pluginName, defaultsByKey, defaults, manuals, loadingPresetOverrides) {
     const manual = spec.manual ?? manuals[spec.id] ?? null;
-    const fnName = spec.function ?? parent.function ?? "";
+    const functions = spec.functions !== null ? [...spec.functions] : [...parent.functions];
+    const fnName = functions[0] ?? parent.function ?? "";
     // Each sub can point at a *different* plugin function than its
-    // siblings (that's the whole point of "add"/"list"/"done" sharing one
-    // parent) — resolve this sub's own default permissions from its own
-    // function, not from whatever function the parent happens to carry.
+    // siblings — resolve this sub's own default permissions from its own
+    // primary function, not from whatever the parent happens to carry.
     const subDef = pluginName && fnName
         ? defaultsByKey.get(pluginCommandKey(pluginName, fnName))?.norm ?? null
         : null;
@@ -187,11 +233,13 @@ function buildSubcommandFromSpec(spec, parent, pluginName, defaultsByKey, defaul
         desc: spec.desc,
         manual,
         function: fnName,
+        functions,
+        loading: spec.loading ?? parent.loading,
         arguments: [...spec.arguments],
         permissions: resolvePermissions(spec.permissions, spec.messages, subDef?.permissions ?? null, defaults.permissions, defaults.messages, parent.permissions.scope),
     };
 }
-function buildSubcommandsFromSpecs(specs, parent, pluginName, defaultsByKey, defaults, manuals) {
+function buildSubcommandsFromSpecs(specs, parent, pluginName, defaultsByKey, defaults, manuals, loadingPresetOverrides) {
     const out = {};
     for (const spec of specs) {
         const token = spec.cmd.toLowerCase();
@@ -202,19 +250,60 @@ function buildSubcommandsFromSpecs(specs, parent, pluginName, defaultsByKey, def
             }));
             continue;
         }
-        out[token] = buildSubcommandFromSpec(spec, parent, pluginName, defaultsByKey, defaults, manuals);
+        out[token] = buildSubcommandFromSpec(spec, parent, pluginName, defaultsByKey, defaults, manuals, loadingPresetOverrides);
     }
     return out;
 }
+/**
+ * Chain inheritance for `loading:` is:
+ *
+ *   defaults.loading  →  categoryLoading[cat]  →  spec.loading
+ *
+ * Returns the first non-null in that order. An inline `spec.loading`
+ * already won against any preset (the parser resolves preset names at
+ * parse time). Categories that don't declare `loading:` pass `null`
+ * through, so the defaults spec wins.
+ */
+function resolveLoadingChain(spec, categoryKey, categoryLoading, defaults) {
+    return spec
+        ?? (categoryKey ? categoryLoading[categoryKey] ?? null : null)
+        ?? defaults.loading
+        ?? null;
+}
 export function buildCommandRegistry(specs, pluginRegistry, defaults = {
     notifyChanges: true,
     notifyPeriodDays: 7,
     notifyMessage: null,
-}, menu = { ...DEFAULT_MENU_CONFIG }, categories = {}, manuals = {}) {
+}, menu = { ...DEFAULT_MENU_CONFIG }, categories = {}, manuals = {}, loadingPresets = {}, categoryLoading = {}, prefix = null) {
     const byId = new Map();
     const byInvocation = new Map();
     const defaultsByKey = new Map();
-    for (const plugin of pluginRegistry.values()) {
+    const coreFunctionNames = new Set();
+    for (const spec of specs ?? []) {
+        for (const fn of spec.functions)
+            coreFunctionNames.add(fn);
+        for (const sub of spec.subcommands) {
+            for (const fn of sub.functions ?? [])
+                coreFunctionNames.add(fn);
+        }
+    }
+    const allPlugins = new Map(pluginRegistry);
+    allPlugins.set("core", {
+        name: "core",
+        status: "active",
+        run: null,
+        setup: null,
+        commands: Object.fromEntries([...coreFunctionNames, "ping", "status"].map((name) => [
+            name,
+            {
+                handler: resolveCoreCommandHandler(name),
+            },
+        ])),
+        exports: null,
+        error: null,
+        guardOptions: { timeout: false },
+    });
+    for (const plugin of allPlugins.values()) {
         if (plugin.status !== "active")
             continue;
         if (!plugin.commands)
@@ -255,26 +344,31 @@ export function buildCommandRegistry(specs, pluginRegistry, defaults = {
                 source: "plugin",
                 pluginName: plugin.name,
                 function: fn,
+                functions: [fn],
+                loading: resolveLoadingChain(null, category, categoryLoading, defaults),
                 handler: norm.handler,
                 text: null,
                 permissions: resolvePermissions(null, null, norm.permissions, defaults.permissions, defaults.messages, category ? categories[category]?.scope : null),
                 arguments: [],
                 subcommands: {},
                 categoryHiddenInScope: null,
+                hiddenOutsideScope: null,
             };
+            entry.hiddenOutsideScope = entry.permissions.hiddenOutsideScope;
             byId.set(id, entry);
         }
     }
     if (specs) {
         for (const spec of specs) {
-            if (spec.plugin && spec.function) {
-                const key = pluginCommandKey(spec.plugin, spec.function);
+            const primaryFn = spec.functions[0] ?? null;
+            if (spec.plugin && primaryFn) {
+                const key = pluginCommandKey(spec.plugin, primaryFn);
                 const pluginDefault = defaultsByKey.get(key);
                 if (!pluginDefault) {
                     logger.warn(t("system.commandRegistryOrphanEntry", {
                         id: spec.id,
                         plugin: spec.plugin,
-                        function: spec.function
+                        function: primaryFn
                     }));
                     continue;
                 }
@@ -289,7 +383,7 @@ export function buildCommandRegistry(specs, pluginRegistry, defaults = {
                         logger.warn(t("system.commandRegistryOrphanEntry", {
                             id: spec.id,
                             plugin: spec.plugin,
-                            function: spec.function
+                            function: primaryFn
                         }));
                         continue;
                     }
@@ -303,14 +397,18 @@ export function buildCommandRegistry(specs, pluginRegistry, defaults = {
                         manual: null,
                         source: "plugin",
                         pluginName: spec.plugin,
-                        function: spec.function,
+                        function: primaryFn,
+                        functions: [primaryFn],
+                        loading: resolveLoadingChain(spec.loading, null, categoryLoading, defaults),
                         handler: norm.handler,
                         text: null,
                         permissions: resolvePermissions(null, null, null, defaults.permissions, defaults.messages, null),
                         arguments: [],
                         subcommands: {},
                         categoryHiddenInScope: null,
+                        hiddenOutsideScope: null,
                     };
+                    existing.hiddenOutsideScope = existing.permissions.hiddenOutsideScope;
                     byId.set(key, existing);
                 }
                 if (spec.cmd)
@@ -325,16 +423,28 @@ export function buildCommandRegistry(specs, pluginRegistry, defaults = {
                     existing.group = spec.group;
                 existing.manual = spec.manual ?? norm.manual ?? manuals[spec.id] ?? manuals[existing.cmd] ?? null;
                 existing.permissions = resolvePermissions(spec.permissions, spec.messages, norm.permissions, defaults.permissions, defaults.messages, existing.category ? categories[existing.category]?.scope : null);
+                // Function chain: explicit `functions:` wins; fall back to the
+                // single primary if the YAML only declared `function:` /
+                // `plugin:` shorthand. Empty list intentionally means "no
+                // handlers" — see `CommandSpec.functions` doc.
+                if (spec.functions.length > 0)
+                    existing.functions = [...spec.functions];
+                else if (primaryFn)
+                    existing.functions = [primaryFn];
                 existing.arguments = [...spec.arguments];
                 existing.categoryHiddenInScope = resolveCategoryHiddenInScope(existing.category, categories);
-                existing.subcommands = buildSubcommandsFromSpecs(spec.subcommands, existing, spec.plugin, defaultsByKey, defaults, manuals);
+                existing.hiddenOutsideScope = existing.permissions.hiddenOutsideScope;
+                existing.loading = resolveLoadingChain(spec.loading, existing.category, categoryLoading, defaults);
+                existing.subcommands = buildSubcommandsFromSpecs(spec.subcommands, existing, spec.plugin, defaultsByKey, defaults, manuals, loadingPresets);
             }
-            else if (spec.plugin && !spec.function && spec.subcommands.length > 0) {
-                // Parent-only container: the top-level entry has no handler of
-                // its own (e.g. `todo:`), it just groups subcommands that each
-                // declare their own `function:`. Never dispatched directly —
-                // resolveDispatch() always routes into one of `subcommands`.
-                const id = `parent::${spec.id}`;
+            else if (spec.plugin && spec.functions.length === 0) {
+                // Metadata-only plugin entry: no handler of its own. Either a
+                // parent container grouping subcommands that each declare their
+                // own `function:` (e.g. `todo:`), or a bare declarative entry
+                // with no subcommands at all — either way `functions` stays
+                // empty and runCommand() short-circuits to "no_dispatch" (see
+                // its `fnNames.length === 0` check).
+                const id = spec.subcommands.length > 0 ? `parent::${spec.id}` : spec.id;
                 const entry = {
                     id,
                     cmd: spec.cmd,
@@ -346,14 +456,17 @@ export function buildCommandRegistry(specs, pluginRegistry, defaults = {
                     source: "plugin",
                     pluginName: spec.plugin,
                     function: null,
+                    functions: [],
+                    loading: resolveLoadingChain(spec.loading, spec.category ?? null, categoryLoading, defaults),
                     handler: null,
                     text: null,
                     permissions: resolvePermissions(spec.permissions, spec.messages, null, defaults.permissions, defaults.messages, spec.category ? categories[spec.category]?.scope : null),
                     arguments: [...spec.arguments],
                     subcommands: {},
                     categoryHiddenInScope: resolveCategoryHiddenInScope(spec.category, categories),
+                    hiddenOutsideScope: resolvePermissions(spec.permissions, spec.messages, null, defaults.permissions, defaults.messages, spec.category ? categories[spec.category]?.scope : null).hiddenOutsideScope,
                 };
-                entry.subcommands = buildSubcommandsFromSpecs(spec.subcommands, entry, spec.plugin, defaultsByKey, defaults, manuals);
+                entry.subcommands = buildSubcommandsFromSpecs(spec.subcommands, entry, spec.plugin, defaultsByKey, defaults, manuals, loadingPresets);
                 byId.set(id, entry);
             }
             else if (!spec.plugin) {
@@ -365,6 +478,7 @@ export function buildCommandRegistry(specs, pluginRegistry, defaults = {
                 }
                 const id = `text::${spec.id}`;
                 const manual = spec.manual ?? manuals[spec.id] ?? manuals[spec.cmd] ?? null;
+                const entryPerms = resolvePermissions(spec.permissions, spec.messages, null, defaults.permissions, defaults.messages, spec.category ? categories[spec.category]?.scope : null);
                 const entry = {
                     id,
                     cmd: spec.cmd,
@@ -376,14 +490,17 @@ export function buildCommandRegistry(specs, pluginRegistry, defaults = {
                     source: "text",
                     pluginName: null,
                     function: null,
+                    functions: [],
+                    loading: resolveLoadingChain(spec.loading, spec.category ?? null, categoryLoading, defaults),
                     handler: null,
                     text: spec.text,
-                    permissions: resolvePermissions(spec.permissions, spec.messages, null, defaults.permissions, defaults.messages, spec.category ? categories[spec.category]?.scope : null),
+                    permissions: entryPerms,
                     arguments: [...spec.arguments],
                     subcommands: {},
                     categoryHiddenInScope: resolveCategoryHiddenInScope(spec.category, categories),
+                    hiddenOutsideScope: entryPerms.hiddenOutsideScope,
                 };
-                entry.subcommands = buildSubcommandsFromSpecs(spec.subcommands, entry, null, defaultsByKey, defaults, manuals);
+                entry.subcommands = buildSubcommandsFromSpecs(spec.subcommands, entry, null, defaultsByKey, defaults, manuals, loadingPresets);
                 byId.set(id, entry);
             }
             else {
@@ -401,26 +518,30 @@ export function buildCommandRegistry(specs, pluginRegistry, defaults = {
             registerInvocationWithDeprecationGuard(byInvocation, alias, entry.id, false, defaults.notifyChanges);
         }
     }
-    // Validate menu cmd + aliases against command invocations
+    // Validate menu cmd + aliases against command invocations. Fully opt-in:
+    // when menu.enabled is false (default), the native menu claims nothing —
+    // "menu"/"help" stay free for a plugin (legacy or commands.yaml) to use.
     const menuAliases = new Set();
-    const menuInvocations = [menu.cmd, ...menu.aliases.filter(a => a !== menu.cmd)];
-    for (const alias of menuInvocations) {
-        const existing = byInvocation.get(alias);
-        if (existing !== undefined) {
-            logger.warn(t("system.commandRegistryMenuAliasCollision", {
-                alias,
-                winner: existing
-            }));
-        }
-        else {
-            menuAliases.add(alias);
+    if (menu.enabled) {
+        const menuInvocations = [menu.cmd, ...menu.aliases.filter(a => a !== menu.cmd)];
+        for (const alias of menuInvocations) {
+            const existing = byInvocation.get(alias);
+            if (existing !== undefined) {
+                logger.warn(t("system.commandRegistryMenuAliasCollision", {
+                    alias,
+                    winner: existing
+                }));
+            }
+            else {
+                menuAliases.add(alias);
+            }
         }
     }
-    return { byId, byInvocation, defaults, menu, menuAliases, categories, manuals };
+    return { byId, byInvocation, defaults, menu, menuAliases, categories, manuals, loadingPresets, categoryLoading, prefix };
 }
 let currentRegistry = null;
 export async function initCommandRegistry() {
-    const config = await loadCommandsConfig();
+    const config = await loadCommandsConfig(new Set(pluginRegistry.keys()));
     const defaults = config?.defaults ?? {
         notifyChanges: true,
         notifyPeriodDays: 7,
@@ -429,8 +550,11 @@ export async function initCommandRegistry() {
     const menu = config?.menu ?? { ...DEFAULT_MENU_CONFIG };
     const categories = config?.categories ?? {};
     const manuals = config?.manuals ?? {};
+    const loadingPresets = config?.loadingPresets ?? {};
+    const categoryLoading = config?.categoryLoading ?? {};
+    const prefix = config?.prefix ?? null;
     const specs = config?.specs ?? [];
-    const registry = buildCommandRegistry(specs, pluginRegistry, defaults, menu, categories, manuals);
+    const registry = buildCommandRegistry(specs, pluginRegistry, defaults, menu, categories, manuals, loadingPresets, categoryLoading, prefix);
     syncCommandHistory(registry.byId, defaults, specs);
     currentRegistry = registry;
     return registry;

package/dist/kernel/commandRegistry.test.js

@@ -80,7 +80,8 @@ describe("kernel/commandRegistry", () => {
             {
                 id: "funPlugin::jokeFn",
                 plugin: "funPlugin",
-                function: "jokeFn",
+                functions: ["jokeFn"],
+                loading: null,
                 cmd: "telljoke",
                 aliases: ["tj"],
                 desc: "Overridden desc",
@@ -114,7 +115,8 @@ describe("kernel/commandRegistry", () => {
             {
                 id: "custom_hello",
                 plugin: null,
-                function: null,
+                functions: [],
+                loading: null,
                 cmd: "hello",
                 aliases: ["hi"],
                 desc: "Says hello",