@manybot/manybot 5.8.0 → 5.9.1

package/dist/kernel/pluginLoader.test.js

@@ -5,8 +5,10 @@ import os from "os";
 import path from "path";
 const configDir = await fs.mkdtemp(path.join(os.tmpdir(), "manybot-plugin-loader-"));
 process.env.MANYBOT_CONFIG_DIR = configDir;
-const { cleanupPlugins, loadPlugin, pluginRegistry, reloadPlugin } = await import("#kernel/pluginLoader.js");
+const { cleanupPlugins, loadPlugin, loadPlugins, pluginRegistry, reloadCommandRegistry, reloadPlugin } = await import("#kernel/pluginLoader.js");
+const { getCommandRegistry } = await import("#kernel/commandRegistry.js");
 const pluginsDir = path.join(configDir, "plugins");
+const commandsFile = path.join(configDir, "commands.yaml");
 async function writePlugin(name, manifest, source) {
     const dir = path.join(pluginsDir, name);
     await fs.mkdir(dir, { recursive: true });
@@ -14,10 +16,22 @@ async function writePlugin(name, manifest, source) {
     if (source !== undefined)
         await fs.writeFile(path.join(dir, "index.js"), source, "utf8");
 }
+async function waitFor(label, read, timeoutMs = 3000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const value = read();
+        if (value !== undefined)
+            return value;
+        await new Promise((r) => setTimeout(r, 50));
+    }
+    throw new Error(`timed out waiting for ${label}`);
+}
 beforeEach(async () => {
     await cleanupPlugins();
     pluginRegistry.clear();
     await fs.rm(pluginsDir, { recursive: true, force: true });
+    await fs.rm(commandsFile, { force: true });
+    await fs.rm(path.join(configDir, "menu.yaml"), { force: true });
 });
 after(async () => {
     await cleanupPlugins();
@@ -78,3 +92,99 @@ describe("kernel/pluginLoader", () => {
         assert.equal(plugin?.errorCount, 0);
     });
 });
+describe("kernel/pluginLoader — commands.yaml hot reload", () => {
+    test("reloadCommandRegistry re-reads commands.yaml and rebuilds the registry", async () => {
+        await writePlugin("reloaddummy", '{"main":"index.js"}', `
+      export default async function run() {}
+    `);
+        await loadPlugins(["reloaddummy"]);
+        await fs.writeFile(commandsFile, `
+defaults:
+  notifyChanges: false
+helloReload:
+  cmd: hello
+  plugin: reloaddummy
+  desc: "First version"
+  functions: []
+`, "utf8");
+        await reloadCommandRegistry();
+        const registry = getCommandRegistry();
+        assert.ok(registry, "registry should be initialized after reload");
+        assert.equal(registry.byInvocation.get("hello"), "helloReload");
+        assert.equal(registry.byId.get("helloReload")?.desc, "First version");
+        assert.equal(registry.defaults.notifyChanges, false);
+        await fs.writeFile(commandsFile, `
+helloReload:
+  cmd: hello
+  plugin: reloaddummy
+  desc: "Second version"
+  functions: []
+`, "utf8");
+        await reloadCommandRegistry();
+        const registry2 = getCommandRegistry();
+        assert.ok(registry2);
+        assert.equal(registry2.byId.get("helloReload")?.desc, "Second version");
+        assert.equal(registry2.defaults.notifyChanges, true, "defaults should reset to built-in when omitted");
+    });
+    test("config watcher reloads the registry when commands.yaml is edited", async () => {
+        await writePlugin("watchdummy", '{"main":"index.js"}', `
+      export default async function run() {}
+    `);
+        await loadPlugins(["watchdummy"]);
+        assert.equal(getCommandRegistry()?.byInvocation.get("watch"), undefined);
+        await fs.writeFile(commandsFile, `
+helloWatch:
+  cmd: watch
+  plugin: watchdummy
+  desc: "Watcher picks this up"
+  functions: []
+`, "utf8");
+        const registry = await waitFor("registry to pick up commands.yaml change", () => {
+            const r = getCommandRegistry();
+            return r?.byId.get("helloWatch")?.desc === "Watcher picks this up" ? r : undefined;
+        });
+        assert.equal(registry.byInvocation.get("watch"), "helloWatch");
+    });
+    test("config watcher reloads the registry when an imported YAML file is edited", async () => {
+        await writePlugin("importdummy", '{"main":"index.js"}', `
+      export default async function run() {}
+    `);
+        await fs.writeFile(path.join(configDir, "menu.yaml"), `
+helloImport:
+  cmd: importcmd
+  plugin: importdummy
+  desc: "From menu.yaml (first)"
+  functions: []
+`, "utf8");
+        await fs.writeFile(commandsFile, `import: menu.yaml\n`, "utf8");
+        await loadPlugins(["importdummy"]);
+        const first = await waitFor("initial import to be picked up", () => {
+            const r = getCommandRegistry();
+            return r?.byId.get("helloImport")?.desc === "From menu.yaml (first)" ? r : undefined;
+        });
+        assert.equal(first.byInvocation.get("importcmd"), "helloImport");
+        await fs.writeFile(path.join(configDir, "menu.yaml"), `
+helloImport:
+  cmd: importcmd
+  plugin: importdummy
+  desc: "From menu.yaml (second)"
+  functions: []
+`, "utf8");
+        const second = await waitFor("imported yaml change to be picked up", () => {
+            const r = getCommandRegistry();
+            return r?.byId.get("helloImport")?.desc === "From menu.yaml (second)" ? r : undefined;
+        });
+        assert.equal(second.byInvocation.get("importcmd"), "helloImport");
+    });
+    test("config watcher ignores non-yaml/non-toml files in PATHS.HOME", async () => {
+        await writePlugin("ignoredummy", '{"main":"index.js"}', `
+      export default async function run() {}
+    `);
+        await loadPlugins(["ignoredummy"]);
+        const registryBefore = getCommandRegistry();
+        await fs.writeFile(path.join(configDir, "README.md"), "unrelated", "utf8");
+        await new Promise((r) => setTimeout(r, 800));
+        const registryAfter = getCommandRegistry();
+        assert.equal(registryAfter, registryBefore, "registry reference must be stable when no relevant file changed");
+    });
+});

package/dist/kernel/runCommand.js

@@ -23,13 +23,16 @@
  *      `for (plugin of pluginRegistry) await runPlugin(...)` loop.
  */
 import { logger } from "#logger";
-import { t } from "#i18n";
+import { tFor } from "#i18n";
 import { CMD_PREFIX } from "#config";
 import { fireAlert } from "./alerts.js";
 import { runPlugin } from "./pluginGuard.js";
 import { checkPermission } from "./commandPermissions.js";
 import { getCommandRegistry } from "./commandRegistry.js";
 import { pluginRegistry, resolvePluginCommandHandler } from "./pluginLoader.js";
+import { STOP_CHAIN } from "./commandsConfig.js";
+import { resolveCoreCommandHandler } from "./coreCommands.js";
+import { getChatLocale, getChatPrefix } from "./chatOverrides.js";
 function flatten(target) {
     if (target.kind === "sub") {
         return {
@@ -89,8 +92,13 @@ export function resolveDispatch(command, rawArgs) {
  * through to the legacy run loop.
  */
 export async function runCommand(opts) {
-    const { resolution, pluginName, ctx, reply } = opts;
+    const { resolution, pluginName, ctx, reply, chatId } = opts;
     const { target } = resolution;
+    // Resolved once per dispatch: this chat's `!config` overrides (or the
+    // global defaults when none were set) for every kernel-authored reply
+    // below (unknown-sub hint, missing-argument usage, ...).
+    const lang = chatId ? getChatLocale(chatId) : undefined;
+    const prefix = chatId ? getChatPrefix(chatId) : CMD_PREFIX;
     if (target.kind === "none") {
         return { status: "no_dispatch", sentReply: null, suggestedReply: null };
     }
@@ -99,7 +107,7 @@ export async function runCommand(opts) {
     // handler — same convention as a CLI tool with an unknown subcommand.
     if (resolution.unmatchedSubToken && target.kind === "parent") {
         const validSubs = Object.keys(target.entry.subcommands);
-        const help = t("commandRun.unknownSubcommand", {
+        const help = tFor(lang, "commandRun.unknownSubcommand", {
             sub: resolution.unmatchedSubToken,
             cmd: target.entry.cmd,
             valid: validSubs.join(", ") || "(none)",
@@ -112,7 +120,7 @@ export async function runCommand(opts) {
     const perm = await checkPermission(permEntry, {
         isGroup: ctx.chat.isGroup,
         chatId: ctx.chat.id,
-        senderId: ctx.msg.sender,
+        sender: { lid: ctx.msg.sender, pn: ctx.msg.senderPn },
         isSenderAdmin: () => ctx.chat.isSenderAdmin(),
         isBotAdmin: () => ctx.chat.isBotAdmin(),
     });
@@ -127,8 +135,8 @@ export async function runCommand(opts) {
     // + auto-generated usage before invoking.
     const requiredCount = flat.arguments.filter(a => a.required).length;
     if (requiredCount > flat.args.length) {
-        const usage = renderUsage(target);
-        const msg = `${t("commandRun.missingRequiredArg")}\n\n${usage}`;
+        const usage = renderUsage(target, prefix);
+        const msg = `${tFor(lang, "commandRun.missingRequiredArg")}\n\n${usage}`;
         await reply.text(msg);
         return { status: "argument_missing", sentReply: msg, suggestedReply: msg };
     }
@@ -139,19 +147,50 @@ export async function runCommand(opts) {
             // text-only command handled below (caller will handle the fixed-text path).
             return { status: "no_dispatch", sentReply: null, suggestedReply: null };
         }
-        // The actual handler invocation is delegated to runPlugin (which
-        // enforces timeout + 3-strikes). Pass the resolved sub-function
-        // name via the unified entrypoint so handlers can be the same
-        // function whether called as the parent or as a sub.
-        const fnName = target.kind === "sub" ? target.sub.function : (target.entry.function ?? target.entry.cmd);
+        // Function chain dispatch — v6 reference yaml allows a command to
+        // declare `functions: [a, b, c]` and have them run top-to-bottom.
+        // Each function receives the same `(ctx, { args, subcommand })`
+        // shape; a function may short-circuit the rest of the chain by
+        // returning the sentinel `STOP_CHAIN` (exported from
+        // `commandsConfig.ts`). Anything else (void/undefined/regular value)
+        // lets the chain continue. Empty chain → "no_dispatch" (parent is
+        // metadata-only, e.g. a sub-container with no override).
+        const fnNames = target.kind === "sub" ? target.sub.functions : target.entry.functions;
+        if (fnNames.length === 0) {
+            return { status: "no_dispatch", sentReply: null, suggestedReply: null };
+        }
+        const subId = target.kind === "sub" ? target.sub.cmd : undefined;
+        const input = { args: flat.args, subcommand: subId };
+        if (pluginName === "core") {
+            for (const fnName of fnNames) {
+                const handler = resolveCoreCommandHandler(fnName);
+                if (!handler) {
+                    logger.warn(`[runCommand] Core namespace does not expose handler "${fnName}"`);
+                    continue;
+                }
+                const result = await handler(ctx, input);
+                if (result === STOP_CHAIN)
+                    break;
+            }
+            return { status: "executed", sentReply: null, suggestedReply: null };
+        }
         const plugin = lookupPlugin(pluginName);
-        const handler = plugin ? resolvePluginCommandHandler(plugin.commands?.[fnName]) : null;
-        if (!plugin || !handler) {
-            const msg = `Plugin "${pluginName}" does not expose handler for !${flat.name}`;
+        if (!plugin) {
+            const msg = `Plugin "${pluginName}" is not active`;
             logger.warn(`[runCommand] ${msg}`);
             return { status: "no_dispatch", sentReply: null, suggestedReply: msg };
         }
-        await runPlugin(plugin, ctx, handler, { args: flat.args, subcommand: target.kind === "sub" ? target.sub.cmd : undefined }, { rethrow: true });
+        for (const fnName of fnNames) {
+            const handler = resolvePluginCommandHandler(plugin.commands?.[fnName]);
+            if (!handler) {
+                const msg = `Plugin "${pluginName}" does not expose handler for !${flat.name}.${fnName}`;
+                logger.warn(`[runCommand] ${msg}`);
+                continue;
+            }
+            const result = await runPlugin(plugin, ctx, handler, input, { rethrow: true });
+            if (result === STOP_CHAIN)
+                break;
+        }
         return { status: "executed", sentReply: null, suggestedReply: null };
     }
     catch (e) {
@@ -216,13 +255,13 @@ function lookupPlugin(pluginName) {
  *   !<cmd>[ <sub>] [--<arg1> ...]
  * Built from the declared `arguments:` block.
  */
-export function renderUsage(target) {
+export function renderUsage(target, prefix = CMD_PREFIX) {
     if (target.kind === "none")
         return "";
     const flat = flatten(target);
     const head = target.kind === "sub"
-        ? `${CMD_PREFIX}${target.parent.cmd} ${target.sub.cmd}`
-        : `${CMD_PREFIX}${flat.entry.cmd}`;
+        ? `${prefix}${target.parent.cmd} ${target.sub.cmd}`
+        : `${prefix}${flat.entry.cmd}`;
     const headClean = head.replace(/\s+$/, "");
     if (flat.arguments.length === 0)
         return headClean;

package/dist/kernel/runCommand.test.js

@@ -3,13 +3,23 @@ import assert from "node:assert/strict";
 import { resolveDispatch, runCommand, renderUsage } from "#kernel/runCommand.js";
 import { buildCommandRegistry, __setRegistryForTests } from "#kernel/commandRegistry.js";
 import { pluginRegistry } from "#kernel/pluginLoader.js";
+import { STOP_CHAIN } from "#kernel/commandsConfig.js";
+import { buildSettingsApi } from "#kernel/settingsDb.js";
+import { CONFIG } from "#config";
+// Pin the "no override" global language independently of whatever
+// ~/.manybot/manybot.toml happens to say on the machine running the
+// suite — CONFIG.LANGUAGE is read from the real config dir unless
+// MANYBOT_CONFIG_DIR is set, and i18n's `currentLang` locks in on the
+// first t()/tFor() call, so this must run before any test does.
+CONFIG.LANGUAGE = "en";
 function emptySpec(overrides) {
     return {
         id: overrides.id ?? "todo::add",
         cmd: overrides.cmd ?? "todo",
         aliases: overrides.aliases ?? [],
         plugin: overrides.plugin ?? "todoPlugin",
-        function: overrides.function ?? "addFn",
+        functions: overrides.functions ?? ["addFn"],
+        loading: overrides.loading ?? null,
         text: overrides.text ?? null,
         desc: overrides.desc ?? null,
         category: overrides.category ?? null,
@@ -28,7 +38,8 @@ function emptySub(overrides) {
         id: overrides.id ?? "todo::list",
         cmd: overrides.cmd ?? "list",
         aliases: overrides.aliases ?? [],
-        function: overrides.function ?? null,
+        functions: overrides.functions ?? null,
+        loading: overrides.loading ?? null,
         desc: overrides.desc ?? null,
         manual: overrides.manual ?? null,
         arguments: overrides.arguments ?? [],
@@ -71,6 +82,11 @@ function registerTodoPlugin() {
                     throw new Error("boom");
                 },
             },
+            gateFn: {
+                cmd: "gate",
+                aliases: [],
+                handler: async () => STOP_CHAIN,
+            },
         },
     };
     pluginRegistry.set("todoPlugin", plugin);
@@ -113,7 +129,7 @@ describe("kernel/runCommand", () => {
         }
     });
     test("resolveDispatch: kind sub when a declared subcommand token matches", () => {
-        const spec = emptySpec({ subcommands: [emptySub({ function: "listFn" })] });
+        const spec = emptySpec({ subcommands: [emptySub({ functions: ["listFn"] })] });
         __setRegistryForTests(buildRegistry([spec]));
         const { target } = resolveDispatch("todo", "list");
         assert.equal(target.kind, "sub");
@@ -122,7 +138,7 @@ describe("kernel/runCommand", () => {
         }
     });
     test("resolveDispatch: unmatchedSubToken falls through to parent", () => {
-        const spec = emptySpec({ subcommands: [emptySub({ function: "listFn" })] });
+        const spec = emptySpec({ subcommands: [emptySub({ functions: ["listFn"] })] });
         __setRegistryForTests(buildRegistry([spec]));
         const { target, unmatchedSubToken } = resolveDispatch("todo", "wat now");
         assert.equal(target.kind, "parent");
@@ -144,7 +160,7 @@ describe("kernel/runCommand", () => {
         assert.equal(replies.length, 0);
     });
     test("runCommand: routes to the subcommand handler, not the parent's", async () => {
-        const spec = emptySpec({ subcommands: [emptySub({ function: "listFn" })] });
+        const spec = emptySpec({ subcommands: [emptySub({ functions: ["listFn"] })] });
         __setRegistryForTests(buildRegistry([spec]));
         const resolution = resolveDispatch("todo", "list");
         const result = await runCommand({
@@ -158,7 +174,7 @@ describe("kernel/runCommand", () => {
         assert.equal(addCalls.length, 0);
     });
     test("runCommand: unmatchedSubToken replies with a usage hint and does not dispatch", async () => {
-        const spec = emptySpec({ subcommands: [emptySub({ function: "listFn" })] });
+        const spec = emptySpec({ subcommands: [emptySub({ functions: ["listFn"] })] });
         __setRegistryForTests(buildRegistry([spec]));
         const resolution = resolveDispatch("todo", "wat");
         const replies = [];
@@ -199,7 +215,7 @@ describe("kernel/runCommand", () => {
         assert.equal(addCalls.length, 0);
     });
     test("runCommand: re-throws on handler crash after firing the alert", async () => {
-        const spec = emptySpec({ id: "todo::crash", cmd: "crashcmd", function: "crashFn" });
+        const spec = emptySpec({ id: "todo::crash", cmd: "crashcmd", functions: ["crashFn"] });
         __setRegistryForTests(buildRegistry([spec]));
         const resolution = resolveDispatch("crashcmd", "");
         await assert.rejects(() => runCommand({
@@ -232,4 +248,250 @@ describe("kernel/runCommand", () => {
         const usage = renderUsage({ kind: "none" });
         assert.equal(usage, "");
     });
+    test("renderUsage: accepts a prefix override", () => {
+        const spec = emptySpec({
+            arguments: [{ name: "item", type: "quoted_text", required: true }],
+        });
+        __setRegistryForTests(buildRegistry([spec]));
+        const { target } = resolveDispatch("todo", "");
+        const usage = renderUsage(target, "#");
+        assert.match(usage, /^#todo /);
+    });
+    describe("per-chat overrides (prefix / language via !config)", () => {
+        const overrideChatId = "5511988887777@c.us"; // already-normalized form
+        beforeEach(() => {
+            buildSettingsApi("core", overrideChatId).deleteAll();
+        });
+        afterEach(() => {
+            buildSettingsApi("core", overrideChatId).deleteAll();
+        });
+        test("missing-argument usage message uses the chat's saved prefix override", async () => {
+            buildSettingsApi("core", overrideChatId).set("chat_prefix", "#");
+            const spec = emptySpec({ arguments: [{ name: "item", type: "quoted_text", required: true }] });
+            __setRegistryForTests(buildRegistry([spec]));
+            const resolution = resolveDispatch("todo", "");
+            const replies = [];
+            const result = await runCommand({
+                pluginName: "todoPlugin",
+                ctx: fakeCtx(),
+                resolution,
+                reply: { text: (t) => replies.push(t) },
+                chatId: overrideChatId,
+            });
+            assert.equal(result.status, "argument_missing");
+            assert.match(replies[0], /#todo/, "usage line should use the chat's saved prefix, not the global one");
+        });
+        test("missing-argument usage message falls back to the global prefix when no override is set", async () => {
+            const spec = emptySpec({ arguments: [{ name: "item", type: "quoted_text", required: true }] });
+            __setRegistryForTests(buildRegistry([spec]));
+            const resolution = resolveDispatch("todo", "");
+            const replies = [];
+            await runCommand({
+                pluginName: "todoPlugin",
+                ctx: fakeCtx(),
+                resolution,
+                reply: { text: (t) => replies.push(t) },
+                chatId: overrideChatId,
+            });
+            assert.match(replies[0], /!todo/);
+        });
+        test("unknown-subcommand message uses the chat's saved language override", async () => {
+            buildSettingsApi("core", overrideChatId).set("chat_locale", "pt");
+            const spec = emptySpec({ subcommands: [emptySub({ functions: ["listFn"] })] });
+            __setRegistryForTests(buildRegistry([spec]));
+            const resolution = resolveDispatch("todo", "wat");
+            const replies = [];
+            await runCommand({
+                pluginName: "todoPlugin",
+                ctx: fakeCtx(),
+                resolution,
+                reply: { text: (t) => replies.push(t) },
+                chatId: overrideChatId,
+            });
+            assert.match(replies[0], /Subcomando "wat" desconhecido/);
+        });
+        test("unknown-subcommand message falls back to the global language when no override is set", async () => {
+            const spec = emptySpec({ subcommands: [emptySub({ functions: ["listFn"] })] });
+            __setRegistryForTests(buildRegistry([spec]));
+            const resolution = resolveDispatch("todo", "wat");
+            const replies = [];
+            await runCommand({
+                pluginName: "todoPlugin",
+                ctx: fakeCtx(),
+                resolution,
+                reply: { text: (t) => replies.push(t) },
+                chatId: overrideChatId,
+            });
+            assert.match(replies[0], /Unknown subcommand "wat"/);
+        });
+        test("omitting chatId behaves exactly like an unset override (backward compatible)", async () => {
+            const spec = emptySpec({ arguments: [{ name: "item", type: "quoted_text", required: true }] });
+            __setRegistryForTests(buildRegistry([spec]));
+            const resolution = resolveDispatch("todo", "");
+            const replies = [];
+            const result = await runCommand({
+                pluginName: "todoPlugin",
+                ctx: fakeCtx(),
+                resolution,
+                reply: { text: (t) => replies.push(t) },
+            });
+            assert.equal(result.status, "argument_missing");
+            assert.match(replies[0], /!todo/);
+        });
+    });
+    describe("functions: chain + STOP_CHAIN", () => {
+        test("runs every function in the chain in declared order", async () => {
+            let second = false;
+            let third = false;
+            const plugin = {
+                name: "chainPlugin",
+                status: "active",
+                run: null,
+                setup: null,
+                exports: {},
+                error: null,
+                guardOptions: {},
+                commands: {
+                    firstFn: { cmd: "todo", aliases: [], handler: async () => { second = true; } },
+                    secondFn: { cmd: "todo", aliases: [], handler: async () => {
+                            assert.equal(second, true, "second handler ran before first finished");
+                            third = true;
+                        } },
+                    thirdFn: { cmd: "todo", aliases: [], handler: async () => {
+                            assert.equal(third, true, "third handler ran before second finished");
+                        } },
+                },
+            };
+            pluginRegistry.set("chainPlugin", plugin);
+            const specs = [
+                {
+                    id: "chainPlugin::firstFn",
+                    cmd: "chain",
+                    aliases: [],
+                    plugin: "chainPlugin",
+                    functions: ["firstFn", "secondFn", "thirdFn"],
+                    loading: null,
+                    text: null,
+                    desc: null,
+                    category: null,
+                    group: null,
+                    manual: null,
+                    deprecatedMessage: null,
+                    notifyChanges: null,
+                    permissions: null,
+                    messages: null,
+                    arguments: [],
+                    subcommands: [],
+                },
+            ];
+            __setRegistryForTests(buildCommandRegistry(specs, pluginRegistry));
+            const resolution = resolveDispatch("chain", "");
+            const result = await runCommand({
+                pluginName: "chainPlugin",
+                ctx: fakeCtx(),
+                resolution,
+                reply: { text: () => { } },
+            });
+            assert.equal(result.status, "executed");
+            assert.equal(third, true);
+            pluginRegistry.delete("chainPlugin");
+        });
+        test("STOP_CHAIN short-circuits the rest of the chain", async () => {
+            let secondRan = false;
+            const plugin = {
+                name: "stopPlugin",
+                status: "active",
+                run: null,
+                setup: null,
+                exports: {},
+                error: null,
+                guardOptions: {},
+                commands: {
+                    firstFn: { cmd: "stop", aliases: [], handler: async () => STOP_CHAIN },
+                    secondFn: { cmd: "stop", aliases: [], handler: async () => { secondRan = true; } },
+                },
+            };
+            pluginRegistry.set("stopPlugin", plugin);
+            const specs = [
+                {
+                    id: "stopPlugin::firstFn",
+                    cmd: "stop",
+                    aliases: [],
+                    plugin: "stopPlugin",
+                    functions: ["firstFn", "secondFn"],
+                    loading: null,
+                    text: null,
+                    desc: null,
+                    category: null,
+                    group: null,
+                    manual: null,
+                    deprecatedMessage: null,
+                    notifyChanges: null,
+                    permissions: null,
+                    messages: null,
+                    arguments: [],
+                    subcommands: [],
+                },
+            ];
+            __setRegistryForTests(buildCommandRegistry(specs, pluginRegistry));
+            const resolution = resolveDispatch("stop", "");
+            const result = await runCommand({
+                pluginName: "stopPlugin",
+                ctx: fakeCtx(),
+                resolution,
+                reply: { text: () => { } },
+            });
+            assert.equal(result.status, "executed");
+            assert.equal(secondRan, false);
+            pluginRegistry.delete("stopPlugin");
+        });
+        test("chain throw propagates and stops the chain", async () => {
+            let secondRan = false;
+            const plugin = {
+                name: "throwPlugin",
+                status: "active",
+                run: null,
+                setup: null,
+                exports: {},
+                error: null,
+                guardOptions: {},
+                commands: {
+                    firstFn: { cmd: "throw", aliases: [], handler: async () => { throw new Error("mid"); } },
+                    secondFn: { cmd: "throw", aliases: [], handler: async () => { secondRan = true; } },
+                },
+            };
+            pluginRegistry.set("throwPlugin", plugin);
+            const specs = [
+                {
+                    id: "throwPlugin::firstFn",
+                    cmd: "throw",
+                    aliases: [],
+                    plugin: "throwPlugin",
+                    functions: ["firstFn", "secondFn"],
+                    loading: null,
+                    text: null,
+                    desc: null,
+                    category: null,
+                    group: null,
+                    manual: null,
+                    deprecatedMessage: null,
+                    notifyChanges: null,
+                    permissions: null,
+                    messages: null,
+                    arguments: [],
+                    subcommands: [],
+                },
+            ];
+            __setRegistryForTests(buildCommandRegistry(specs, pluginRegistry));
+            const resolution = resolveDispatch("throw", "");
+            await assert.rejects(() => runCommand({
+                pluginName: "throwPlugin",
+                ctx: fakeCtx(),
+                resolution,
+                reply: { text: () => { } },
+            }), /mid/);
+            assert.equal(secondRan, false);
+            pluginRegistry.delete("throwPlugin");
+        });
+    });
 });

package/dist/kernel/settingsDb.js

@@ -94,6 +94,17 @@ function dbDelete(pluginName, chatId, key) {
 function dbDeleteAll(pluginName, chatId) {
     stmts.deleteAll.run(pluginName, chatId);
 }
+/**
+ * Direct read of a single (plugin, chat, key) setting, bypassing the
+ * `ctx.settings` scoped-accessor pattern. For call sites that need a
+ * value before a `PluginContext` exists yet — e.g. resolving the
+ * per-chat command prefix while still parsing the incoming message,
+ * or resolving the per-chat language from outside the "core" plugin's
+ * own context. See `kernel/chatOverrides.ts`.
+ */
+export function getPluginSetting(pluginName, chatId, key) {
+    return dbGet(pluginName, chatId, key);
+}
 // ── Scoped accessor factory ───────────────────────────────────────────────────
 /**
  * Returns a settings accessor for a specific (pluginName, chatId) pair.
@@ -106,9 +117,11 @@ function scopedAccessor(pluginName, chatId) {
          * @param {string} key
          * @param {*}      [defaultValue]
          */
-        get(key, defaultValue = undefined) {
+        get(key, defaultValue) {
             const val = dbGet(pluginName, chatId, key);
-            return val !== undefined ? val : defaultValue;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- `get<T>` is a
+            // type-level convenience for callers; the store itself is untyped JSON.
+            return (val !== undefined ? val : defaultValue);
         },
         /**
          * Get all settings for this chat as a plain object.

package/dist/kernel/testConfig.js

@@ -12,6 +12,15 @@
  *        c. otherwise absent (`chat === null`) — integration tests skip
  *           with an explanatory message instead of crashing.
  *
+ *      This module accepts any chat shape `normalizeTestChat()` allows,
+ *      including a group (`@g.us`) — it has no opinion on what a given
+ *      test file actually needs. Individual suites are the ones with
+ *      that requirement: contacts.integration.test.ts, for instance,
+ *      needs an individual chat (a phone number, or a JID ending in
+ *      `@s.whatsapp.net`/`@c.us`/`@lid`) because it asserts on
+ *      per-person contact fields (LID, number, country) that a group
+ *      simply doesn't have — see that file's own header for details.
+ *
  *   2. `runWhatsApp` — explicit opt-in flag (env `MANYBOT_RUN_WHATSAPP_TESTS=1`).
  *      A saved WhatsApp session plus a `TEST_CHAT` is NOT enough to fire real
  *      messages; this is the single, deliberate signal that the operator