@manybot/manybot 5.7.0 → 5.9.0

package/dist/kernel/commandsConfig.js

@@ -0,0 +1,949 @@
+import fs from "fs/promises";
+import path from "path";
+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")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function asAliasList(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const item of value) {
+        if (typeof item !== "string")
+            continue;
+        const trimmed = item.trim();
+        if (trimmed.length > 0)
+            out.push(trimmed);
+    }
+    return out;
+}
+function asImportList(value) {
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? [trimmed] : [];
+    }
+    return asAliasList(value);
+}
+function asBool(value) {
+    if (typeof value === "boolean")
+        return value;
+    return null;
+}
+function asPositiveInt(value, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0)
+        return fallback;
+    return Math.floor(value);
+}
+export function parseLocalizedString(raw) {
+    if (typeof raw === "string") {
+        const trimmed = raw.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    if (raw !== null && typeof raw === "object" && !Array.isArray(raw)) {
+        const out = {};
+        for (const [lang, val] of Object.entries(raw)) {
+            if (typeof val === "string") {
+                const trimmed = val.trim();
+                if (trimmed.length > 0)
+                    out[lang] = trimmed;
+            }
+        }
+        return Object.keys(out).length > 0 ? out : null;
+    }
+    return null;
+}
+export async function resolveFileRef(value) {
+    if (!value)
+        return null;
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (trimmed.startsWith("file:")) {
+            const relativePath = trimmed.slice(5).trim();
+            const fullPath = path.resolve(PATHS.HOME, relativePath);
+            try {
+                return await fs.readFile(fullPath, "utf8");
+            }
+            catch (e) {
+                const err = e;
+                logger.warn(`commandsConfig: failed to read file ref "${trimmed}" (${fullPath}): ${err.message}`);
+                return trimmed;
+            }
+        }
+        return trimmed;
+    }
+    if (typeof value === "object" && value !== null) {
+        const out = {};
+        for (const [lang, val] of Object.entries(value)) {
+            if (typeof val === "string") {
+                const resolved = await resolveFileRef(val);
+                if (resolved && typeof resolved === "string") {
+                    out[lang] = resolved;
+                }
+            }
+        }
+        return Object.keys(out).length > 0 ? out : null;
+    }
+    return null;
+}
+function parseGroupUserList(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const obj = raw;
+    const groups = asAliasList(obj.groups);
+    const users = asAliasList(obj.users);
+    if (groups.length === 0 && users.length === 0)
+        return undefined;
+    return {
+        groups: groups.length > 0 ? groups : undefined,
+        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;
+    const obj = raw;
+    const admin = asBool(obj.admin) ?? undefined;
+    const botAdmin = asBool(obj.botAdmin) ?? undefined;
+    const owner = asBool(obj.owner) ?? undefined;
+    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;
+    }
+    // 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 &&
+        dono === undefined &&
+        allowedChats.length === 0 &&
+        hiddenOutsideScope === undefined &&
+        obj.group_only === undefined &&
+        obj.dm_only === undefined) {
+        return null;
+    }
+    return {
+        admin,
+        botAdmin,
+        owner,
+        scope,
+        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) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const obj = 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;
+    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",
+]);
+function parseArgument(raw, parentId) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const obj = raw;
+    const name = asString(obj.name);
+    if (!name) {
+        logger.warn(t("system.commandsConfigArgumentMissingName", { id: parentId }));
+        return null;
+    }
+    const typeStr = asString(obj.type);
+    if (!typeStr) {
+        logger.warn(t("system.commandsConfigArgumentMissingType", { id: parentId, name }));
+        return null;
+    }
+    // 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;
+    }
+    // `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 (normalizedType === "choice") {
+        choices = asAliasList(obj.choices);
+        if (choices.length === 0) {
+            logger.warn(t("system.commandsConfigChoiceArgumentNoChoices", { id: parentId, name }));
+            // Still allow the argument; renderUsage just falls back to "<name>".
+        }
+    }
+    return {
+        name,
+        type: normalizedType,
+        required,
+        choices,
+    };
+}
+function parseArguments(raw, parentId) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw)) {
+        logger.warn(t("system.commandsConfigArgumentsNotList", { id: parentId }));
+        return [];
+    }
+    const out = [];
+    for (const item of raw) {
+        const arg = parseArgument(item, parentId);
+        if (arg)
+            out.push(arg);
+    }
+    return out;
+}
+async function parseSubcommand(parentId, raw, presets, onPlugin) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const obj = raw;
+    const cmd = asString(obj.cmd);
+    if (!cmd) {
+        logger.warn(t("system.commandsConfigSubcommandMissingCmd", { id: parentId }));
+        return null;
+    }
+    const id = `${parentId}::${cmd}`;
+    const rawManual = parseLocalizedString(obj.manual);
+    const manual = rawManual ? await resolveFileRef(rawManual) : null;
+    return {
+        id,
+        cmd,
+        aliases: asAliasList(obj.aliases),
+        // 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 ?? obj.args, id),
+        permissions: parsePermissions(obj.permissions),
+        messages: parseMessages(obj.messages),
+    };
+}
+async function parseSubcommands(raw, parentId, presets, onPlugin) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw)) {
+        logger.warn(t("system.commandsConfigSubcommandsNotList", { id: parentId }));
+        return [];
+    }
+    const out = [];
+    for (const item of raw) {
+        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.",
+        pt: "Use {prefix}<comando> para executar ou {prefix}help <comando> para ver o manual.",
+        es: "Usa {prefix}<comando> para ejecutarlo o {prefix}help <comando> para ver el manual.",
+    },
+    footer: null,
+    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: 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),
+    };
+}
+function parseScopeValue(raw) {
+    const s = asString(raw)?.toLowerCase();
+    if (s === "group" || s === "dm" || s === "any")
+        return s;
+    return null;
+}
+function parseCategories(raw, presets) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        return { categories: {}, categoryLoading: {} };
+    }
+    const obj = raw;
+    const categories = {};
+    const categoryLoading = {};
+    for (const [catKey, value] of Object.entries(obj)) {
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            continue;
+        const catObj = value;
+        const label = parseLocalizedString(catObj.label) ?? catKey;
+        const order = typeof catObj.order === "number" && Number.isFinite(catObj.order) ? catObj.order : 999;
+        const scope = parseScopeValue(catObj.scope);
+        const hiddenInScope = parseScopeValue(catObj.hiddenInScope);
+        categories[catKey] = {
+            label,
+            order,
+            scope: scope ?? null,
+            hiddenInScope: hiddenInScope ?? null,
+        };
+        const loading = parseLoadingSpec(catObj.loading, `categories.${catKey}`, presets);
+        if (loading)
+            categoryLoading[catKey] = loading;
+    }
+    return { categories, categoryLoading };
+}
+async function parseManuals(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    const obj = raw;
+    const out = {};
+    for (const [id, value] of Object.entries(obj)) {
+        const parsed = parseLocalizedString(value);
+        if (parsed) {
+            const resolved = await resolveFileRef(parsed);
+            if (resolved)
+                out[id] = resolved;
+        }
+    }
+    return out;
+}
+const DEFAULT_NOTIFY_CHANGES = true;
+const DEFAULT_NOTIFY_PERIOD_DAYS = 7;
+function parseDefaults(raw, presets) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        return {
+            notifyChanges: DEFAULT_NOTIFY_CHANGES,
+            notifyPeriodDays: DEFAULT_NOTIFY_PERIOD_DAYS,
+            notifyMessage: null,
+            permissions: null,
+            messages: null,
+            loading: null,
+        };
+    }
+    const obj = raw;
+    return {
+        notifyChanges: asBool(obj.notifyChanges) ?? DEFAULT_NOTIFY_CHANGES,
+        notifyPeriodDays: asPositiveInt(obj.notifyPeriodDays, DEFAULT_NOTIFY_PERIOD_DAYS),
+        notifyMessage: asString(obj.notifyMessage),
+        permissions: parsePermissions(obj.permissions),
+        messages: parseMessages(obj.messages),
+        loading: parseLoadingSpec(obj.loading, "defaults", presets),
+    };
+}
+/**
+ * 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", {
+            id,
+            path: COMMANDS_FILE
+        }));
+        return null;
+    }
+    const rawText = parseLocalizedString(raw.text);
+    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,
+        functions: functions ?? [],
+        loading: parseLoadingSpec(raw.loading, id, presets),
+        text,
+        desc: parseLocalizedString(raw.desc),
+        category: asString(raw.category),
+        group: asString(raw.group),
+        manual,
+        deprecatedMessage: asString(raw.deprecatedMessage),
+        notifyChanges: asBool(raw.notifyChanges),
+        permissions: parsePermissions(raw.permissions),
+        messages: parseMessages(raw.messages),
+        arguments: parseArguments(raw.arguments ?? raw.args, id),
+        subcommands,
+    };
+}
+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
+ * into the main root object. Each top-level key (`menu`, `manuals`, a
+ * command id, ...) may be owned by exactly one source file — no deep
+ * merge, first owner wins and any later collision is reported as an
+ * error and skipped, keeping the rest of that import file usable.
+ */
+async function resolveImports(root) {
+    const importPaths = asImportList(root.import);
+    if (importPaths.length === 0)
+        return root;
+    const merged = { ...root };
+    delete merged.import;
+    const owner = new Map();
+    for (const key of Object.keys(merged))
+        owner.set(key, COMMANDS_FILE);
+    for (const relPath of importPaths) {
+        const fullPath = path.resolve(PATHS.HOME, relPath);
+        let raw;
+        try {
+            raw = await fs.readFile(fullPath, "utf8");
+        }
+        catch (e) {
+            const err = e;
+            logger.error(t("system.commandsConfigImportReadFailed", { path: fullPath, message: err.message }));
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = yaml.load(raw, { filename: fullPath });
+        }
+        catch (e) {
+            const err = e;
+            logger.error(t("system.commandsConfigImportParseFailed", { path: fullPath, message: err.message }));
+            continue;
+        }
+        if (parsed === null || parsed === undefined)
+            continue;
+        if (typeof parsed !== "object" || Array.isArray(parsed)) {
+            logger.error(t("system.commandsConfigImportInvalidRoot", { path: fullPath }));
+            continue;
+        }
+        for (const [key, value] of Object.entries(parsed)) {
+            if (key === "import") {
+                logger.warn(t("system.commandsConfigImportNested", { path: fullPath }));
+                continue;
+            }
+            const existingOwner = owner.get(key);
+            if (existingOwner !== undefined) {
+                logger.error(t("system.commandsConfigImportKeyConflict", { key, path: fullPath, owner: existingOwner }));
+                continue;
+            }
+            merged[key] = value;
+            owner.set(key, fullPath);
+        }
+    }
+    return merged;
+}
+/**
+ * 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");
+    }
+    catch (e) {
+        const err = e;
+        if (err.code === "ENOENT")
+            return null;
+        logger.error(t("system.commandsConfigReadFailed", {
+            path: COMMANDS_FILE,
+            message: err.message
+        }));
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = yaml.load(raw, { filename: COMMANDS_FILE });
+    }
+    catch (e) {
+        const err = e;
+        logger.error(t("system.commandsConfigParseFailed", {
+            path: COMMANDS_FILE,
+            message: err.message
+        }));
+        return null;
+    }
+    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: [],
+        };
+    }
+    if (typeof parsed !== "object" || Array.isArray(parsed)) {
+        logger.error(t("system.commandsConfigInvalidRoot", {
+            path: COMMANDS_FILE
+        }));
+        return null;
+    }
+    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, categoryLoading } = parseCategories(root.categories, loadingPresets);
+    const manuals = await parseManuals(root.manuals);
+    const out = [];
+    for (const [id, value] of Object.entries(root)) {
+        if (RESERVED_KEYS.has(id))
+            continue;
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+            logger.warn(t("system.commandsConfigInvalidEntry", {
+                id,
+                path: COMMANDS_FILE
+            }));
+            continue;
+        }
+        const spec = await parseEntry(id, value, loadingPresets, validPluginKeys);
+        if (spec)
+            out.push(spec);
+    }
+    return { prefix, defaults, menu, categories, manuals, loadingPresets, categoryLoading, specs: out };
+}