@manybot/manybot 5.8.0 → 5.9.0

package/dist/kernel/commandsConfig.js

@@ -4,6 +4,12 @@ import * as yaml from "js-yaml";
 import { logger } from "#logger";
 import { t } from "#i18n";
 import { PATHS } from "#config";
+/**
+ * Sentinel returned from a command function to short-circuit the chain of
+ * `functions:`. Anything else (including `undefined` and a void return)
+ * lets the next function in the list run with the same args.
+ */
+export const STOP_CHAIN = Symbol.for("manybot.stopChain");
 const COMMANDS_FILE = path.join(PATHS.HOME, "commands.yaml");
 function asString(value) {
     if (typeof value !== "string")
@@ -107,6 +113,29 @@ function parseGroupUserList(raw) {
         users: users.length > 0 ? users : undefined,
     };
 }
+/**
+ * Map the flat-form scope aliases (`group_only` / `dm_only`) plus an
+ * explicit `scope:` into a single resolved "group" | "dm" | "any" | undefined
+ * value. `group_only: true` and `dm_only: true` are mutually exclusive —
+ * when both are set the function logs a warning and prefers the explicit
+ * `scope:` (or `group_only` if `scope` is also absent).
+ */
+function parseScopeFromFlat(obj) {
+    const explicit = asString(obj.scope)?.toLowerCase();
+    if (explicit === "group" || explicit === "dm" || explicit === "any")
+        return explicit;
+    const groupOnly = obj.group_only;
+    const dmOnly = obj.dm_only;
+    if (asBool(groupOnly) === true && asBool(dmOnly) === true) {
+        logger.warn(t("system.commandsConfigConflictingScopeFlags", { id: "(permissions)" }));
+        return undefined;
+    }
+    if (asBool(groupOnly) === true)
+        return "group";
+    if (asBool(dmOnly) === true)
+        return "dm";
+    return undefined;
+}
 function parsePermissions(raw) {
     if (raw === null || typeof raw !== "object" || Array.isArray(raw))
         return null;
@@ -114,24 +143,46 @@ function parsePermissions(raw) {
     const admin = asBool(obj.admin) ?? undefined;
     const botAdmin = asBool(obj.botAdmin) ?? undefined;
     const owner = asBool(obj.owner) ?? undefined;
-    let scope = undefined;
-    const scopeStr = asString(obj.scope)?.toLowerCase();
-    if (scopeStr === "group" || scopeStr === "dm" || scopeStr === "any") {
-        scope = scopeStr;
-    }
+    const scope = parseScopeFromFlat(obj);
+    const dono = asString(obj.dono) ?? undefined;
     let cooldownSeconds = undefined;
     if (typeof obj.cooldownSeconds === "number" && Number.isFinite(obj.cooldownSeconds) && obj.cooldownSeconds >= 0) {
         cooldownSeconds = obj.cooldownSeconds;
     }
-    const whitelist = parseGroupUserList(obj.whitelist);
-    const blacklist = parseGroupUserList(obj.blacklist);
+    // Canonical nested whitelist/blacklist, with the flat-form
+    // `whitelist_groups` / `blacklist_users` fields merged in.
+    const nestedWhitelist = parseGroupUserList(obj.whitelist);
+    const nestedBlacklist = parseGroupUserList(obj.blacklist);
+    const flatWhitelistGroups = asAliasList(obj.whitelist_groups);
+    const flatBlacklistUsers = asAliasList(obj.blacklist_users);
+    let whitelist = nestedWhitelist;
+    if (flatWhitelistGroups.length > 0) {
+        whitelist = {
+            groups: [...(nestedWhitelist?.groups ?? []), ...flatWhitelistGroups],
+            users: nestedWhitelist?.users,
+        };
+    }
+    let blacklist = nestedBlacklist;
+    if (flatBlacklistUsers.length > 0) {
+        blacklist = {
+            groups: nestedBlacklist?.groups,
+            users: [...(nestedBlacklist?.users ?? []), ...flatBlacklistUsers],
+        };
+    }
+    const allowedChats = asAliasList(obj.allowed_chats);
+    const hiddenOutsideScope = asBool(obj.hidden_outside_scope) ?? undefined;
     if (admin === undefined &&
         botAdmin === undefined &&
         owner === undefined &&
         scope === undefined &&
         cooldownSeconds === undefined &&
         whitelist === undefined &&
-        blacklist === undefined) {
+        blacklist === undefined &&
+        dono === undefined &&
+        allowedChats.length === 0 &&
+        hiddenOutsideScope === undefined &&
+        obj.group_only === undefined &&
+        obj.dm_only === undefined) {
         return null;
     }
     return {
@@ -142,6 +193,13 @@ function parsePermissions(raw) {
         cooldownSeconds,
         whitelist,
         blacklist,
+        dono: dono ?? undefined,
+        groupOnly: obj.group_only !== undefined ? asBool(obj.group_only) ?? undefined : undefined,
+        dmOnly: obj.dm_only !== undefined ? asBool(obj.dm_only) ?? undefined : undefined,
+        whitelistGroups: flatWhitelistGroups.length > 0 ? flatWhitelistGroups : undefined,
+        blacklistUsers: flatBlacklistUsers.length > 0 ? flatBlacklistUsers : undefined,
+        allowedChats: allowedChats.length > 0 ? allowedChats : undefined,
+        hiddenOutsideScope,
     };
 }
 function parseMessages(raw) {
@@ -151,19 +209,150 @@ function parseMessages(raw) {
     const botNotAdmin = asString(obj.botNotAdmin) ?? undefined;
     const senderNotAdmin = asString(obj.senderNotAdmin) ?? undefined;
     const ownerOnly = asString(obj.ownerOnly) ?? undefined;
+    const donoOnly = asString(obj.donoOnly) ?? undefined;
     const wrongScope = asString(obj.wrongScope) ?? undefined;
     const cooldown = asString(obj.cooldown) ?? undefined;
-    if (!botNotAdmin && !senderNotAdmin && !ownerOnly && !wrongScope && !cooldown) {
+    const blacklist = asString(obj.blacklist) ?? undefined;
+    const allowedChats = asString(obj.allowedChats) ?? undefined;
+    if (!botNotAdmin && !senderNotAdmin && !ownerOnly && !donoOnly && !wrongScope && !cooldown && !blacklist && !allowedChats) {
         return null;
     }
     return {
         botNotAdmin,
         senderNotAdmin,
         ownerOnly,
+        donoOnly,
         wrongScope,
         cooldown,
+        blacklist,
+        allowedChats,
     };
 }
+/**
+ * Translate the reference yaml's flat `permission_messages:` block into a
+ * `CommandMessages` shape — same keys, just renamed. Stored alongside the
+ * rest of `defaults.messages` so per-command `messages:` overrides still
+ * take precedence.
+ */
+function parsePermissionMessagesBlock(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const obj = raw;
+    return parseMessages({
+        botNotAdmin: obj.admin_only,
+        senderNotAdmin: obj.admin_only,
+        ownerOnly: obj.dono_only,
+        donoOnly: obj.dono_only,
+        wrongScope: obj.group_only ?? obj.dm_only,
+        cooldown: obj.cooldown,
+        blacklist: obj.blacklist,
+        allowedChats: obj.allowed_chats,
+    });
+}
+// ── Loading indicator parsing ────────────────────────────────────────────────
+const LOADING_TYPES = new Set([
+    "reaction", "typing", "recording_audio", "spinner", "none",
+]);
+const LOADING_PROPS_BY_TYPE = {
+    reaction: ["icon", "onSuccess", "on_success", "onError", "on_error"],
+    typing: [],
+    recording_audio: [],
+    spinner: ["frames", "intervalMs", "interval_ms", "onSuccess", "on_success", "onError", "on_error"],
+    none: [],
+};
+/**
+ * Parse a single `loading:` value, which can be:
+ *   - a preset name (string) — looked up in `presets`
+ *   - an inline object: `{ type, ... }`
+ * Returns the resolved spec, or `null` when the value is absent. Throws
+ * nothing: malformed entries log a warning and are dropped (we keep going
+ * with `null`, which means "no override; fall back to the next level in
+ * the inheritance chain").
+ */
+function parseLoadingSpec(raw, contextId, presets) {
+    if (raw === undefined || raw === null)
+        return null;
+    // `loading: spinner_classico` (preset reference)
+    if (typeof raw === "string") {
+        const trimmed = raw.trim();
+        if (trimmed.length === 0)
+            return null;
+        const preset = presets[trimmed];
+        if (!preset) {
+            logger.warn(t("system.commandsConfigLoadingPresetMissing", { id: contextId, name: trimmed }));
+            return null;
+        }
+        return preset;
+    }
+    // Inline: `loading: { type: reaction, icon: "⏳", ... }`
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        logger.warn(t("system.commandsConfigLoadingInvalid", { id: contextId }));
+        return null;
+    }
+    const obj = raw;
+    const typeStr = asString(obj.type)?.toLowerCase();
+    if (!typeStr || !LOADING_TYPES.has(typeStr)) {
+        logger.warn(t("system.commandsConfigLoadingUnknownType", { id: contextId, type: typeStr ?? "(none)" }));
+        return null;
+    }
+    const type = typeStr;
+    const allowed = new Set(LOADING_PROPS_BY_TYPE[type]);
+    const recognized = [];
+    for (const key of Object.keys(obj)) {
+        if (key === "type")
+            continue;
+        if (!allowed.has(key)) {
+            logger.error(t("system.commandsConfigLoadingUnknownProp", { id: contextId, type, key }));
+            return null; // malformed config — fail closed
+        }
+        recognized.push(key);
+    }
+    const spec = { type };
+    if (type === "reaction" || type === "spinner") {
+        if (obj.icon !== undefined) {
+            const icon = asString(obj.icon);
+            if (icon)
+                spec.icon = icon;
+        }
+        if (obj.onSuccess !== undefined || obj.on_success !== undefined) {
+            const s = asString(obj.onSuccess ?? obj.on_success);
+            if (s)
+                spec.onSuccess = s;
+        }
+        if (obj.onError !== undefined || obj.on_error !== undefined) {
+            const s = asString(obj.onError ?? obj.on_error);
+            if (s)
+                spec.onError = s;
+        }
+    }
+    if (type === "spinner") {
+        if (obj.frames !== undefined) {
+            const frames = asAliasList(obj.frames);
+            if (frames.length > 0)
+                spec.frames = frames;
+        }
+        if (obj.intervalMs !== undefined || obj.interval_ms !== undefined) {
+            const rawVal = obj.intervalMs ?? obj.interval_ms;
+            const n = typeof rawVal === "number" && Number.isFinite(rawVal) && rawVal >= 100
+                ? Math.max(1000, Math.floor(rawVal))
+                : null;
+            if (n !== null)
+                spec.intervalMs = n;
+        }
+    }
+    return spec;
+}
+function parseLoadingPresets(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [name, value] of Object.entries(raw)) {
+        const spec = parseLoadingSpec(value, `loading_presets.${name}`, {});
+        if (spec)
+            out[name] = spec;
+    }
+    return out;
+}
 const ARGUMENT_TYPES = new Set([
     "mention", "url", "media_direct", "media_reply", "number",
     "duration", "choice", "boolean", "quoted_text", "reply",
@@ -182,13 +371,28 @@ function parseArgument(raw, parentId) {
         logger.warn(t("system.commandsConfigArgumentMissingType", { id: parentId, name }));
         return null;
     }
-    if (!ARGUMENT_TYPES.has(typeStr)) {
+    // Reference yaml uses `media_direct_or_reply` (the bot accepts either a
+    // direct media attachment or a reply-with-media). It's a superset of
+    // `media_reply`, so we silently normalize it down.
+    const normalizedType = typeStr === "media_direct_or_reply" ? "media_reply" : typeStr;
+    if (!ARGUMENT_TYPES.has(normalizedType)) {
         logger.warn(t("system.commandsConfigUnknownArgType", { id: parentId, name, type: typeStr }));
         return null;
     }
-    const required = asBool(obj.required) ?? false;
+    // `required: true` and `optional: true` are two ways to say the same
+    // thing in opposite directions. The reference yaml prefers `optional:`.
+    let required;
+    if (asBool(obj.required) !== null) {
+        required = asBool(obj.required) ?? false;
+    }
+    else if (asBool(obj.optional) !== null) {
+        required = !(asBool(obj.optional) ?? false);
+    }
+    else {
+        required = false;
+    }
     let choices;
-    if (typeStr === "choice") {
+    if (normalizedType === "choice") {
         choices = asAliasList(obj.choices);
         if (choices.length === 0) {
             logger.warn(t("system.commandsConfigChoiceArgumentNoChoices", { id: parentId, name }));
@@ -197,7 +401,7 @@ function parseArgument(raw, parentId) {
     }
     return {
         name,
-        type: typeStr,
+        type: normalizedType,
         required,
         choices,
     };
@@ -217,7 +421,7 @@ function parseArguments(raw, parentId) {
     }
     return out;
 }
-async function parseSubcommand(parentId, raw) {
+async function parseSubcommand(parentId, raw, presets, onPlugin) {
     if (raw === null || typeof raw !== "object" || Array.isArray(raw))
         return null;
     const obj = raw;
@@ -233,15 +437,20 @@ async function parseSubcommand(parentId, raw) {
         id,
         cmd,
         aliases: asAliasList(obj.aliases),
-        function: asString(obj.function),
+        // Per-sub function chain. `functions: [...]` wins; a single
+        // `function: "x"` becomes a one-element list. `null` means "inherit
+        // the parent's chain at build time" — the kernel resolves that in
+        // commandRegistry, not here.
+        functions: parseFunctionList(obj.function, obj.functions, onPlugin),
+        loading: parseLoadingSpec(obj.loading, id, presets),
         desc: parseLocalizedString(obj.desc),
         manual,
-        arguments: parseArguments(obj.arguments, id),
+        arguments: parseArguments(obj.arguments ?? obj.args, id),
         permissions: parsePermissions(obj.permissions),
         messages: parseMessages(obj.messages),
     };
 }
-async function parseSubcommands(raw, parentId) {
+async function parseSubcommands(raw, parentId, presets, onPlugin) {
     if (raw === undefined || raw === null)
         return [];
     if (!Array.isArray(raw)) {
@@ -250,13 +459,62 @@ async function parseSubcommands(raw, parentId) {
     }
     const out = [];
     for (const item of raw) {
-        const sub = await parseSubcommand(parentId, item);
+        const sub = await parseSubcommand(parentId, item, presets, onPlugin);
         if (sub)
             out.push(sub);
     }
     return out;
 }
+/**
+ * Resolve `function:` (single name) and/or `functions:` (ordered list)
+ * into a single ordered chain. Reference yaml mixes both forms per command.
+ * Empty result means "inherit the parent's chain at build time" — the
+ * spec carries `null` to flag that, and the registry resolves it.
+ *
+ * Qualified items use the `plugin.function` form. `core` is the reserved
+ * kernel namespace; external plugins use their canonical `owner/plugin` key.
+ * The registry stores and dispatches only the function portion because a
+ * command has one owning plugin.
+ */
+function splitQualifiedFunction(value) {
+    const dot = value.indexOf(".");
+    if (dot <= 0 || dot === value.length - 1) {
+        return { plugin: null, functionName: value };
+    }
+    return {
+        plugin: value.slice(0, dot),
+        functionName: value.slice(dot + 1),
+    };
+}
+function parseFunctionList(single, list, onPlugin) {
+    if (list !== undefined && list !== null) {
+        if (!Array.isArray(list))
+            return [];
+        const out = [];
+        for (const item of list) {
+            const s = asString(item);
+            if (s) {
+                const qualified = splitQualifiedFunction(s);
+                if (qualified.plugin)
+                    onPlugin?.(qualified.plugin);
+                out.push(qualified.functionName);
+            }
+        }
+        return out;
+    }
+    if (single !== undefined && single !== null) {
+        const s = asString(single);
+        if (!s)
+            return [];
+        const qualified = splitQualifiedFunction(s);
+        if (qualified.plugin)
+            onPlugin?.(qualified.plugin);
+        return [qualified.functionName];
+    }
+    return null;
+}
 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.",
@@ -267,23 +525,34 @@ const DEFAULT_MENU_CONFIG = {
     cmd: "menu",
     aliases: ["help", "man", "menu", "bot", "?"],
     notFoundFallback: false,
+    suggestSimilar: false,
+    suggestMaxDistance: 2,
     welcomeMessage: null,
     welcomeWindowDays: 3,
     pageSize: 15,
 };
 function parseMenu(raw) {
+    if (raw === undefined) {
+        return { ...DEFAULT_MENU_CONFIG };
+    }
     if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
         return { ...DEFAULT_MENU_CONFIG };
     }
     const obj = raw;
     const aliases = asAliasList(obj.aliases);
     return {
+        // Block present in commands.yaml → enabled by default; `enabled: false`
+        // inside it still opts back out (e.g. keeping notFoundFallback/welcome
+        // config without claiming the menu/help invocations).
+        enabled: asBool(obj.enabled) ?? true,
         title: parseLocalizedString(obj.title) ?? DEFAULT_MENU_CONFIG.title,
         intro: parseLocalizedString(obj.intro) ?? DEFAULT_MENU_CONFIG.intro,
         footer: parseLocalizedString(obj.footer) ?? DEFAULT_MENU_CONFIG.footer,
         cmd: asString(obj.cmd) ?? DEFAULT_MENU_CONFIG.cmd,
-        aliases: aliases.length > 0 ? aliases : [...DEFAULT_MENU_CONFIG.aliases],
+        aliases: obj.aliases !== undefined ? aliases : [...DEFAULT_MENU_CONFIG.aliases],
         notFoundFallback: asBool(obj.notFoundFallback) ?? DEFAULT_MENU_CONFIG.notFoundFallback,
+        suggestSimilar: asBool(obj.suggestSimilar) ?? DEFAULT_MENU_CONFIG.suggestSimilar,
+        suggestMaxDistance: asPositiveInt(obj.suggestMaxDistance, DEFAULT_MENU_CONFIG.suggestMaxDistance),
         welcomeMessage: parseLocalizedString(obj.welcomeMessage) ?? DEFAULT_MENU_CONFIG.welcomeMessage,
         welcomeWindowDays: asPositiveInt(obj.welcomeWindowDays, DEFAULT_MENU_CONFIG.welcomeWindowDays),
         pageSize: asPositiveInt(obj.pageSize, DEFAULT_MENU_CONFIG.pageSize),
@@ -295,11 +564,13 @@ function parseScopeValue(raw) {
         return s;
     return null;
 }
-function parseCategories(raw) {
-    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
-        return {};
+function parseCategories(raw, presets) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        return { categories: {}, categoryLoading: {} };
+    }
     const obj = raw;
-    const out = {};
+    const categories = {};
+    const categoryLoading = {};
     for (const [catKey, value] of Object.entries(obj)) {
         if (value === null || typeof value !== "object" || Array.isArray(value))
             continue;
@@ -308,14 +579,17 @@ function parseCategories(raw) {
         const order = typeof catObj.order === "number" && Number.isFinite(catObj.order) ? catObj.order : 999;
         const scope = parseScopeValue(catObj.scope);
         const hiddenInScope = parseScopeValue(catObj.hiddenInScope);
-        out[catKey] = {
+        categories[catKey] = {
             label,
             order,
             scope: scope ?? null,
             hiddenInScope: hiddenInScope ?? null,
         };
+        const loading = parseLoadingSpec(catObj.loading, `categories.${catKey}`, presets);
+        if (loading)
+            categoryLoading[catKey] = loading;
     }
-    return out;
+    return { categories, categoryLoading };
 }
 async function parseManuals(raw) {
     if (raw === null || typeof raw !== "object" || Array.isArray(raw))
@@ -334,7 +608,7 @@ async function parseManuals(raw) {
 }
 const DEFAULT_NOTIFY_CHANGES = true;
 const DEFAULT_NOTIFY_PERIOD_DAYS = 7;
-function parseDefaults(raw) {
+function parseDefaults(raw, presets) {
     if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
         return {
             notifyChanges: DEFAULT_NOTIFY_CHANGES,
@@ -342,6 +616,7 @@ function parseDefaults(raw) {
             notifyMessage: null,
             permissions: null,
             messages: null,
+            loading: null,
         };
     }
     const obj = raw;
@@ -351,9 +626,47 @@ function parseDefaults(raw) {
         notifyMessage: asString(obj.notifyMessage),
         permissions: parsePermissions(obj.permissions),
         messages: parseMessages(obj.messages),
+        loading: parseLoadingSpec(obj.loading, "defaults", presets),
     };
 }
-async function parseEntry(id, raw) {
+/**
+ * Normalize the value of a `plugin:` entry against the live
+ * `pluginRegistry`. The parser runs after `loadPlugins()` has populated
+ * the registry, so by the time this fires every active plugin is
+ * reachable under its full `owner/repo` key.
+ *
+ * Accepted shapes:
+ *   - full registry key `owner/repo` — used verbatim if it matches;
+ *   - bare `name` (no slash) — resolved to the unique `.../name` key
+ *     in the registry. If zero keys match, the original `name` is
+ *     returned. If more than one matches, the original `name` is also
+ *     returned so the ambiguity surfaces at dispatch instead of being
+ *     silently resolved by picking one owner;
+ *   - inline `owner/repo.fn` or `name.fn` — split on the first dot by
+ *     `parseEntry` before reaching here; only the prefix half is
+ *     passed in.
+ *
+ * Pure: no I/O, no module imports. The registry is passed in because
+ * importing `pluginLoader.ts` from this file would close a
+ * commandsConfig to pluginLoader to commandRegistry to commandsConfig
+ * cycle (this module already imports types from commandRegistry).
+ */
+function resolvePluginKey(raw, validPluginKeys) {
+    if (validPluginKeys.has(raw))
+        return raw;
+    if (raw.includes("/"))
+        return raw;
+    let match = null;
+    for (const key of validPluginKeys) {
+        if (key.endsWith("/" + raw)) {
+            if (match !== null)
+                return raw;
+            match = key;
+        }
+    }
+    return match ?? raw;
+}
+async function parseEntry(id, raw, presets, validPluginKeys) {
     const cmd = asString(raw.cmd);
     if (!cmd) {
         logger.warn(t("system.commandsConfigMissingCmd", {
@@ -366,12 +679,52 @@ async function parseEntry(id, raw) {
     const text = rawText ? await resolveFileRef(rawText) : null;
     const rawManual = parseLocalizedString(raw.manual);
     const manual = rawManual ? await resolveFileRef(rawManual) : null;
+    // `plugin:` accepts both an `owner/repo` registry key (the canonical
+    // form) and the legacy shorthand `name` (resolved against the active
+    // `pluginRegistry` keys passed in via `validPluginKeys`). It also
+    // accepts an inline form split on the first dot, where everything
+    // after the dot is a function name treated as the head of the
+    // `functions:` chain. When `validPluginKeys` is provided the parser
+    // prefers an exact registry key and falls back to a `/<plugin>` suffix
+    // match (one plugin per name across owners); without it the value is
+    // used verbatim and the caller is responsible for resolving it.
+    const pluginFull = asString(raw.plugin);
+    let plugin = null;
+    let inlineFn = null;
+    if (pluginFull) {
+        const dot = pluginFull.indexOf(".");
+        if (dot >= 0) {
+            plugin = pluginFull.slice(0, dot);
+            inlineFn = pluginFull.slice(dot + 1);
+        }
+        else {
+            plugin = pluginFull;
+        }
+        if (validPluginKeys)
+            plugin = resolvePluginKey(plugin, validPluginKeys);
+    }
+    // `function:` → `functions: [fn]`, `functions: [...]` → as-is,
+    // "core.ping" inline above → `[ping]`, no fields → null (inherit).
+    let functionPlugin = null;
+    const inlineFunctions = parseFunctionList(raw.function, raw.functions, (name) => {
+        functionPlugin ??= name;
+    });
+    const functions = inlineFn !== null
+        ? [inlineFn, ...(inlineFunctions ?? [])]
+        : inlineFunctions;
+    const subcommands = await parseSubcommands(raw.subcommands, id, presets, (name) => {
+        functionPlugin ??= name;
+    });
+    if (!plugin && functionPlugin) {
+        plugin = resolvePluginKey(functionPlugin, validPluginKeys ?? new Set());
+    }
     return {
         id,
         cmd,
         aliases: asAliasList(raw.aliases),
-        plugin: asString(raw.plugin),
-        function: asString(raw.function),
+        plugin,
+        functions: functions ?? [],
+        loading: parseLoadingSpec(raw.loading, id, presets),
         text,
         desc: parseLocalizedString(raw.desc),
         category: asString(raw.category),
@@ -381,11 +734,17 @@ async function parseEntry(id, raw) {
         notifyChanges: asBool(raw.notifyChanges),
         permissions: parsePermissions(raw.permissions),
         messages: parseMessages(raw.messages),
-        arguments: parseArguments(raw.arguments, id),
-        subcommands: await parseSubcommands(raw.subcommands, id),
+        arguments: parseArguments(raw.arguments ?? raw.args, id),
+        subcommands,
     };
 }
-const RESERVED_KEYS = new Set(["defaults", "menu", "categories", "manuals", "import"]);
+const RESERVED_KEYS = new Set([
+    "defaults", "menu", "categories", "manuals", "import",
+    "loading_presets", "loading",
+    "prefix",
+    "notify_changes", "notify_period_days", "deprecation_message", "permission_messages",
+    "commands",
+]);
 /**
  * Resolves `import:` (a path or list of paths, relative to PATHS.HOME) by
  * reading each referenced YAML file and folding its top-level sections
@@ -445,7 +804,45 @@ async function resolveImports(root) {
     }
     return merged;
 }
-export async function loadCommandsConfig() {
+/**
+ * Unwrap a `commands:` wrapper block, if present, so the rest of the
+ * loader doesn't need to know whether the user wrote
+ *
+ *     mycommand:
+ *       cmd: foo
+ *
+ * or
+ *
+ *     commands:
+ *       mycommand:
+ *         cmd: foo
+ *
+ * Both forms get parsed identically. The reference yaml uses the wrapper
+ * because it's clearer once you also have a `defaults:` block at the top
+ * (otherwise the command ids sit at the same indent as `defaults` and the
+ * file looks ambiguous).
+ */
+function unwrapCommandsWrapper(root) {
+    const wrapper = root.commands;
+    if (wrapper === undefined || wrapper === null)
+        return root;
+    if (typeof wrapper !== "object" || Array.isArray(wrapper)) {
+        logger.error(t("system.commandsConfigCommandsWrapperInvalid"));
+        return root;
+    }
+    const inner = wrapper;
+    const out = { ...root };
+    delete out.commands;
+    for (const [key, value] of Object.entries(inner)) {
+        if (key in out) {
+            logger.error(t("system.commandsConfigCommandsWrapperCollision", { key }));
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+}
+export async function loadCommandsConfig(validPluginKeys) {
     let raw;
     try {
         raw = await fs.readFile(COMMANDS_FILE, "utf8");
@@ -474,16 +871,20 @@ export async function loadCommandsConfig() {
     }
     if (parsed === null || parsed === undefined) {
         return {
+            prefix: null,
             defaults: {
                 notifyChanges: DEFAULT_NOTIFY_CHANGES,
                 notifyPeriodDays: DEFAULT_NOTIFY_PERIOD_DAYS,
                 notifyMessage: null,
                 permissions: null,
                 messages: null,
+                loading: null,
             },
             menu: { ...DEFAULT_MENU_CONFIG },
             categories: {},
             manuals: {},
+            loadingPresets: {},
+            categoryLoading: {},
             specs: [],
         };
     }
@@ -493,10 +894,41 @@ export async function loadCommandsConfig() {
         }));
         return null;
     }
-    const root = await resolveImports(parsed);
-    const defaults = parseDefaults(root.defaults);
+    const imported = await resolveImports(parsed);
+    const root = unwrapCommandsWrapper(imported);
+    const prefix = asString(root.prefix) ?? null;
+    const loadingPresets = parseLoadingPresets(root.loading_presets);
+    // Top-level notify_*/deprecation_message/permission_messages/loading act
+    // as a shallow overlay over `defaults:` — when present, each key wins
+    // over the same key under `defaults:`. Same shape, no deep merge (same
+    // rule as imports).
+    const defaultsRaw = (root.defaults ?? {});
+    const notifyChangesTop = asBool(root.notify_changes);
+    const notifyPeriodTop = typeof root.notify_period_days === "number" && Number.isFinite(root.notify_period_days)
+        ? root.notify_period_days
+        : null;
+    const deprecationMessageTop = asString(root.deprecation_message);
+    const permissionMessagesTop = parsePermissionMessagesBlock(root.permission_messages);
+    const mergedDefaults = { ...defaultsRaw };
+    if (notifyChangesTop !== null)
+        mergedDefaults.notifyChanges = notifyChangesTop;
+    if (notifyPeriodTop !== null)
+        mergedDefaults.notifyPeriodDays = notifyPeriodTop;
+    if (deprecationMessageTop !== null)
+        mergedDefaults.notifyMessage = deprecationMessageTop;
+    if (permissionMessagesTop)
+        mergedDefaults.messages = {
+            ...(defaultsRaw.messages ?? {}),
+            ...permissionMessagesTop,
+        };
+    // Top-level `loading: <preset-name-or-inline-spec>` — reference yaml's
+    // global default (`loading: padrao`). Only overlays when actually
+    // present; `defaults.loading` (nested form) still works on its own.
+    if (root.loading !== undefined)
+        mergedDefaults.loading = root.loading;
+    const defaults = parseDefaults(mergedDefaults, loadingPresets);
     const menu = parseMenu(root.menu);
-    const categories = parseCategories(root.categories);
+    const { categories, categoryLoading } = parseCategories(root.categories, loadingPresets);
     const manuals = await parseManuals(root.manuals);
     const out = [];
     for (const [id, value] of Object.entries(root)) {
@@ -509,9 +941,9 @@ export async function loadCommandsConfig() {
             }));
             continue;
         }
-        const spec = await parseEntry(id, value);
+        const spec = await parseEntry(id, value, loadingPresets, validPluginKeys);
         if (spec)
             out.push(spec);
     }
-    return { defaults, menu, categories, manuals, specs: out };
+    return { prefix, defaults, menu, categories, manuals, loadingPresets, categoryLoading, specs: out };
 }