@manybot/manybot 5.7.0 → 5.9.0

package/dist/kernel/commandRegistry.js

@@ -0,0 +1,583 @@
+/**
+ * commandRegistry.ts
+ *
+ * Merges commands.yaml user overrides with each active plugin's
+ * `commands` defaults into a single, in-memory registry — the single
+ * source of truth for command routing. No routing happens here yet
+ * (that's the next step); this module just builds the structure and
+ * can be exercised in isolation with a unit test.
+ */
+import { logger } from "#logger";
+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;
+    const botAdmin = specPerms?.botAdmin ?? pluginPerms?.botAdmin ?? false;
+    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
+        ? {
+            groups: rawWhitelist.groups ? [...rawWhitelist.groups] : [],
+            users: rawWhitelist.users ? [...rawWhitelist.users] : [],
+        }
+        : null;
+    const blacklist = rawBlacklist
+        ? {
+            groups: rawBlacklist.groups ? [...rawBlacklist.groups] : [],
+            users: rawBlacklist.users ? [...rawBlacklist.users] : [],
+        }
+        : null;
+    const messages = {
+        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,
+        botAdmin,
+        scope,
+        owner,
+        cooldownSeconds,
+        whitelist,
+        blacklist,
+        dono,
+        allowedChats,
+        hiddenOutsideScope,
+        messages,
+    };
+}
+function pluginCommandKey(pluginName, functionName) {
+    return `${pluginName}::${functionName}`;
+}
+/**
+ * Plugin-provided command defaults (`export const commands = {...}`) are
+ * plain JS, not parsed/validated YAML — a plugin can hand us any runtime
+ * value regardless of the `PluginCommandDefault` compile-time type. `cmd`
+ * and `aliases` end up bound to SQLite params (deprecation lookups) and a
+ * non-string/undefined value there throws instead of failing gracefully.
+ * Sanitize before it ever reaches the registry.
+ */
+function sanitizePluginCmd(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function sanitizePluginAliases(value) {
+    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 normalizePluginCommand(def) {
+    const handler = resolvePluginCommandHandler(def);
+    if (def && typeof def === "object") {
+        return {
+            cmd: sanitizePluginCmd(def.cmd),
+            aliases: sanitizePluginAliases(def.aliases),
+            desc: def.desc ?? null,
+            category: typeof def.category === "string" ? def.category : null,
+            manual: def.manual ?? null,
+            permissions: def.permissions ?? null,
+            handler,
+        };
+    }
+    // Bare function (pure-function style — no built-in identity), or
+    // something malformed entirely (handler stays null in that case).
+    return { cmd: null, aliases: [], desc: null, category: null, manual: null, permissions: null, handler };
+}
+/** Whether a `commands[fn]` export is a shape worth remembering at all —
+ *  a bare handler function, or an object (even one missing `handler`,
+ *  which is only validated at dispatch time, same as before this
+ *  module supported the bare-function shape). Anything else (a string,
+ *  a number, null/undefined) is not a command definition. */
+function isUsablePluginCommandExport(def) {
+    return typeof def === "function" || (def !== null && typeof def === "object");
+}
+function registerInvocation(byInvocation, text, entryId, isOverride) {
+    const existing = byInvocation.get(text);
+    if (existing === undefined) {
+        byInvocation.set(text, entryId);
+        return true;
+    }
+    if (existing === entryId)
+        return true;
+    logger.warn(t("system.commandRegistryInvocationCollision", {
+        text,
+        winner: existing,
+        loser: entryId,
+        via: isOverride ? "yaml override" : "plugin default"
+    }));
+    return false;
+}
+function registerInvocationWithDeprecationGuard(byInvocation, text, entryId, isOverride, notifyChanges) {
+    if (!notifyChanges) {
+        return registerInvocation(byInvocation, text, entryId, isOverride);
+    }
+    const deprecation = getActiveDeprecation(text);
+    if (deprecation && deprecation.id !== entryId) {
+        logger.warn(t("system.commandDeprecationReservedInvocation", {
+            text,
+            id: deprecation.id
+        }));
+        return false;
+    }
+    return registerInvocation(byInvocation, text, entryId, isOverride);
+}
+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.",
+        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 resolveCategoryHiddenInScope(category, categories) {
+    if (!category)
+        return null;
+    return categories[category]?.hiddenInScope ?? null;
+}
+/**
+ * Resolve a `CommandSubcommandSpec` into the runtime `CommandSubcommand`.
+ *
+ * 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, loadingPresetOverrides) {
+    const manual = spec.manual ?? manuals[spec.id] ?? null;
+    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 — 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;
+    return {
+        id: spec.id,
+        cmd: spec.cmd,
+        aliases: [...spec.aliases],
+        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, loadingPresetOverrides) {
+    const out = {};
+    for (const spec of specs) {
+        const token = spec.cmd.toLowerCase();
+        if (out[token]) {
+            logger.warn(t("system.commandsConfigDuplicateSubcommand", {
+                id: parent.id,
+                cmd: spec.cmd
+            }));
+            continue;
+        }
+        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 = {}, loadingPresets = {}, categoryLoading = {}, prefix = null) {
+    const byId = new Map();
+    const byInvocation = new Map();
+    const defaultsByKey = new Map();
+    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)
+            continue;
+        for (const [fn, def] of Object.entries(plugin.commands)) {
+            const id = pluginCommandKey(plugin.name, fn);
+            // Only a genuinely broken export (not a function and not an
+            // object at all) is unusable no matter what commands.yaml says
+            // later — that's the one case worth a warning + a full skip.
+            if (!isUsablePluginCommandExport(def)) {
+                logger.warn(t("system.commandRegistryInvalidPluginCommand", {
+                    id,
+                    plugin: plugin.name,
+                    function: fn
+                }));
+                continue;
+            }
+            const norm = normalizePluginCommand(def);
+            // Remembered regardless of whether the plugin gave it a `cmd` —
+            // a "pure function" export (bare handler, no built-in identity)
+            // is only reachable once a commands.yaml entry supplies `cmd`,
+            // but it still needs to be findable by pluginCommandKey() below.
+            // A malformed `cmd` (present but not a usable string) also lands
+            // here silently — not an error, just no auto-registration.
+            defaultsByKey.set(id, { plugin, fn, norm });
+            if (!norm.cmd)
+                continue; // no built-in identity — yaml-only until overridden
+            const manual = norm.manual ?? manuals[id] ?? manuals[norm.cmd] ?? null;
+            const category = norm.category;
+            const entry = {
+                id,
+                cmd: norm.cmd,
+                aliases: norm.aliases,
+                desc: norm.desc,
+                category,
+                group: null,
+                manual,
+                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) {
+            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: primaryFn
+                    }));
+                    continue;
+                }
+                const norm = pluginDefault.norm;
+                let existing = byId.get(key);
+                if (!existing) {
+                    // Pure-function plugin export: no auto-registered entry yet
+                    // (norm.cmd was null), so commands.yaml is the sole source of
+                    // `cmd`. Without it there's nothing to invoke this command by.
+                    const cmd = spec.cmd;
+                    if (!cmd) {
+                        logger.warn(t("system.commandRegistryOrphanEntry", {
+                            id: spec.id,
+                            plugin: spec.plugin,
+                            function: primaryFn
+                        }));
+                        continue;
+                    }
+                    existing = {
+                        id: key,
+                        cmd,
+                        aliases: [],
+                        desc: null,
+                        category: null,
+                        group: null,
+                        manual: null,
+                        source: "plugin",
+                        pluginName: spec.plugin,
+                        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)
+                    existing.cmd = spec.cmd;
+                if (spec.aliases.length > 0)
+                    existing.aliases = [...spec.aliases];
+                if (spec.desc)
+                    existing.desc = spec.desc;
+                if (spec.category)
+                    existing.category = spec.category;
+                if (spec.group !== null)
+                    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.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.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,
+                    aliases: [...spec.aliases],
+                    desc: spec.desc,
+                    category: spec.category ?? null,
+                    group: spec.group,
+                    manual: spec.manual ?? manuals[spec.id] ?? manuals[spec.cmd] ?? null,
+                    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, loadingPresets);
+                byId.set(id, entry);
+            }
+            else if (!spec.plugin) {
+                if (!spec.text) {
+                    logger.warn(t("system.commandRegistryInvalidEntry", {
+                        id: spec.id
+                    }));
+                    continue;
+                }
+                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,
+                    aliases: [...spec.aliases],
+                    desc: spec.desc,
+                    category: spec.category ?? null,
+                    group: spec.group,
+                    manual,
+                    source: "text",
+                    pluginName: null,
+                    function: null,
+                    functions: [],
+                    loading: resolveLoadingChain(spec.loading, spec.category ?? null, categoryLoading, defaults),
+                    handler: null,
+                    text: spec.text,
+                    permissions: entryPerms,
+                    arguments: [...spec.arguments],
+                    subcommands: {},
+                    categoryHiddenInScope: resolveCategoryHiddenInScope(spec.category, categories),
+                    hiddenOutsideScope: entryPerms.hiddenOutsideScope,
+                };
+                entry.subcommands = buildSubcommandsFromSpecs(spec.subcommands, entry, null, defaultsByKey, defaults, manuals, loadingPresets);
+                byId.set(id, entry);
+            }
+            else {
+                // spec.plugin set, but neither `function:` nor a non-empty
+                // `subcommands:` block — nothing tells the kernel what to run.
+                logger.warn(t("system.commandRegistryInvalidEntry", {
+                    id: spec.id
+                }));
+            }
+        }
+    }
+    for (const entry of byId.values()) {
+        registerInvocationWithDeprecationGuard(byInvocation, entry.cmd, entry.id, false, defaults.notifyChanges);
+        for (const alias of entry.aliases) {
+            registerInvocationWithDeprecationGuard(byInvocation, alias, entry.id, false, defaults.notifyChanges);
+        }
+    }
+    // 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();
+    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, loadingPresets, categoryLoading, prefix };
+}
+let currentRegistry = null;
+export async function initCommandRegistry() {
+    const config = await loadCommandsConfig(new Set(pluginRegistry.keys()));
+    const defaults = config?.defaults ?? {
+        notifyChanges: true,
+        notifyPeriodDays: 7,
+        notifyMessage: null,
+    };
+    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, loadingPresets, categoryLoading, prefix);
+    syncCommandHistory(registry.byId, defaults, specs);
+    currentRegistry = registry;
+    return registry;
+}
+export function getCommandRegistry() {
+    return currentRegistry;
+}
+/**
+ * Test-only: inject a registry built with {@link buildCommandRegistry}
+ * directly, bypassing `initCommandRegistry()`'s disk config + real
+ * `pluginRegistry` load. Lets `runCommand.test.ts` exercise
+ * `resolveDispatch()`/`runCommand()`, which read the module-singleton
+ * `currentRegistry` and have no injectable-registry parameter (unlike
+ * `commandAccess.ts`'s functions). Pass `null` to reset.
+ */
+export function __setRegistryForTests(registry) {
+    currentRegistry = registry;
+}
+export function getCommandByInvocation(command) {
+    if (!currentRegistry)
+        return null;
+    const id = currentRegistry.byInvocation.get(command);
+    if (id === undefined)
+        return null;
+    return currentRegistry.byId.get(id) ?? null;
+}