@manybot/manybot 5.7.0 → 5.8.0

package/dist/kernel/commandsConfig.test.js

@@ -0,0 +1,236 @@
+import assert from "node:assert/strict";
+import { after, beforeEach, describe, test } from "node:test";
+import fs from "fs/promises";
+import os from "os";
+import path from "path";
+const configDir = await fs.mkdtemp(path.join(os.tmpdir(), "manybot-commands-config-"));
+process.env.MANYBOT_CONFIG_DIR = configDir;
+const { loadCommandsConfig, parseLocalizedString, resolveFileRef } = await import("#kernel/commandsConfig.js");
+const commandsFile = path.join(configDir, "commands.yaml");
+beforeEach(async () => {
+    await fs.rm(commandsFile, { force: true });
+});
+after(async () => {
+    await fs.rm(configDir, { recursive: true, force: true });
+});
+describe("kernel/commandsConfig", () => {
+    test("parses localized strings and preserves only usable values", () => {
+        assert.equal(parseLocalizedString("  hello  "), "hello");
+        assert.equal(parseLocalizedString("   "), null);
+        assert.deepEqual(parseLocalizedString({ en: " Hello ", pt: " Olá ", invalid: 3 }), {
+            en: "Hello",
+            pt: "Olá",
+        });
+        assert.equal(parseLocalizedString([]), null);
+    });
+    test("returns null when commands.yaml does not exist", async () => {
+        assert.equal(await loadCommandsConfig(), null);
+    });
+    test("uses defaults for an empty YAML document", async () => {
+        await fs.writeFile(commandsFile, "null\n", "utf8");
+        const config = await loadCommandsConfig();
+        assert.ok(config);
+        assert.equal(config.defaults.notifyChanges, true);
+        assert.equal(config.defaults.notifyPeriodDays, 7);
+        assert.deepEqual(config.menu.aliases, ["help", "man", "menu", "bot", "?"]);
+        assert.deepEqual(config.specs, []);
+    });
+    test("rejects malformed and non-object YAML roots", async () => {
+        await fs.writeFile(commandsFile, "commands: [unterminated", "utf8");
+        assert.equal(await loadCommandsConfig(), null);
+        await fs.writeFile(commandsFile, "- not\n- a mapping\n", "utf8");
+        assert.equal(await loadCommandsConfig(), null);
+    });
+    test("loads defaults, menu, categories, manuals, file references and command permissions", async () => {
+        await fs.writeFile(path.join(configDir, "reply.txt"), "Reply from file", "utf8");
+        await fs.writeFile(path.join(configDir, "manual-pt.txt"), "Manual em português", "utf8");
+        await fs.writeFile(commandsFile, `
+defaults:
+  notifyChanges: false
+  notifyPeriodDays: 12.8
+  notifyMessage: " Command changed "
+  permissions:
+    admin: true
+    scope: GROUP
+    cooldownSeconds: 4
+    whitelist:
+      groups: [ " group@g.us ", 1 ]
+      users: [ " user@c.us " ]
+  messages:
+    cooldown: " Wait "
+menu:
+  title: { en: " Commands ", pt: " Comandos " }
+  intro: " Intro "
+  footer: " Footer "
+  aliases: [ help, " ? ", 1 ]
+  notFoundFallback: true
+categories:
+  fun:
+    label: { en: " Fun " }
+    order: 2
+  uncategorized: {}
+manuals:
+  greeting: "file: manual-pt.txt"
+hello:
+  cmd: " hello "
+  aliases: [ hi, " oi ", 3 ]
+  plugin: " sample "
+  function: " greet "
+  text: "file: reply.txt"
+  desc: { en: " Say hello ", pt: " Diga oi " }
+  category: " fun "
+  manual: { pt: "file: manual-pt.txt", en: " Plain manual " }
+  deprecatedMessage: " Old command "
+  notifyChanges: false
+  permissions:
+    botAdmin: true
+    owner: false
+    scope: dm
+    cooldownSeconds: 0
+    blacklist:
+      users: [ blocked@c.us ]
+  messages:
+    ownerOnly: " Owners only "
+invalid: "not a command"
+missingCmd:
+  aliases: [ no ]
+`, "utf8");
+        const config = await loadCommandsConfig();
+        assert.ok(config);
+        assert.deepEqual(config.defaults, {
+            notifyChanges: false,
+            notifyPeriodDays: 12,
+            notifyMessage: "Command changed",
+            permissions: {
+                admin: true,
+                botAdmin: undefined,
+                owner: undefined,
+                scope: "group",
+                cooldownSeconds: 4,
+                whitelist: { groups: ["group@g.us"], users: ["user@c.us"] },
+                blacklist: undefined,
+            },
+            messages: { botNotAdmin: undefined, senderNotAdmin: undefined, ownerOnly: undefined, wrongScope: undefined, cooldown: "Wait" },
+        });
+        assert.deepEqual(config.menu, {
+            title: { en: "Commands", pt: "Comandos" },
+            intro: "Intro",
+            footer: "Footer",
+            cmd: "menu",
+            aliases: ["help", "?"],
+            notFoundFallback: true,
+            welcomeMessage: null,
+            welcomeWindowDays: 3,
+            pageSize: 15,
+        });
+        assert.deepEqual(config.categories, {
+            fun: { label: { en: "Fun" }, order: 2, scope: null, hiddenInScope: null },
+            uncategorized: { label: "uncategorized", order: 999, scope: null, hiddenInScope: null },
+        });
+        assert.deepEqual(config.manuals, { greeting: "Manual em português" });
+        assert.equal(config.specs.length, 1);
+        assert.deepEqual(config.specs[0], {
+            id: "hello",
+            cmd: "hello",
+            aliases: ["hi", "oi"],
+            plugin: "sample",
+            function: "greet",
+            text: "Reply from file",
+            desc: { en: "Say hello", pt: "Diga oi" },
+            category: "fun",
+            group: null,
+            manual: { pt: "Manual em português", en: "Plain manual" },
+            deprecatedMessage: "Old command",
+            notifyChanges: false,
+            permissions: {
+                admin: undefined,
+                botAdmin: true,
+                owner: false,
+                scope: "dm",
+                cooldownSeconds: 0,
+                whitelist: undefined,
+                blacklist: { groups: undefined, users: ["blocked@c.us"] },
+            },
+            messages: { botNotAdmin: undefined, senderNotAdmin: undefined, ownerOnly: "Owners only", wrongScope: undefined, cooldown: undefined },
+            arguments: [],
+            subcommands: [],
+        });
+    });
+    test("keeps an unreadable file reference as the original text", async () => {
+        assert.equal(await resolveFileRef("file: missing.txt"), "file: missing.txt");
+        assert.deepEqual(await resolveFileRef({ en: "file: missing.txt", pt: "Texto" }), {
+            en: "file: missing.txt",
+            pt: "Texto",
+        });
+    });
+    test("import: merges top-level sections from auxiliary files", async () => {
+        await fs.writeFile(path.join(configDir, "menu.yaml"), `
+menu:
+  title: "Imported Menu"
+  aliases: ["ajuda"]
+`, "utf8");
+        await fs.writeFile(path.join(configDir, "manual.yaml"), `
+manuals:
+  hello: "Imported manual"
+`, "utf8");
+        await fs.writeFile(commandsFile, `
+import:
+  - menu.yaml
+  - manual.yaml
+hello:
+  cmd: hello
+  plugin: sample
+  function: greet
+`, "utf8");
+        const config = await loadCommandsConfig();
+        assert.ok(config);
+        assert.equal(config.menu.title, "Imported Menu");
+        assert.deepEqual(config.menu.aliases, ["ajuda"]);
+        assert.deepEqual(config.manuals, { hello: "Imported manual" });
+        assert.equal(config.specs.length, 1);
+        assert.equal(config.specs[0].id, "hello");
+    });
+    test("import: accepts a single path (not wrapped in a list)", async () => {
+        await fs.writeFile(path.join(configDir, "menu.yaml"), `
+menu:
+  title: "Solo Import"
+`, "utf8");
+        await fs.writeFile(commandsFile, `
+import: menu.yaml
+`, "utf8");
+        const config = await loadCommandsConfig();
+        assert.ok(config);
+        assert.equal(config.menu.title, "Solo Import");
+    });
+    test("import: a key already owned by the main file or an earlier import is kept, not overwritten", async () => {
+        await fs.writeFile(path.join(configDir, "menu.yaml"), `
+menu:
+  title: "Should be ignored"
+`, "utf8");
+        await fs.writeFile(commandsFile, `
+import:
+  - menu.yaml
+menu:
+  title: "Main file wins"
+`, "utf8");
+        const config = await loadCommandsConfig();
+        assert.ok(config);
+        assert.equal(config.menu.title, "Main file wins");
+    });
+    test("import: a missing or malformed import file is skipped without failing the whole load", async () => {
+        await fs.writeFile(path.join(configDir, "broken.yaml"), "not: [a, valid\n", "utf8");
+        await fs.writeFile(commandsFile, `
+import:
+  - does-not-exist.yaml
+  - broken.yaml
+hello:
+  cmd: hello
+  plugin: sample
+  function: greet
+`, "utf8");
+        const config = await loadCommandsConfig();
+        assert.ok(config);
+        assert.equal(config.specs.length, 1);
+        assert.equal(config.specs[0].id, "hello");
+    });
+});

package/dist/kernel/contactAutoSave.test.js

@@ -0,0 +1,87 @@
+import test, { describe } from "node:test";
+import assert from "node:assert/strict";
+import { trackIncomingForContactSave } from "#kernel/contactAutoSave.js";
+function createMockContract() {
+    const saved = [];
+    return {
+        savedContacts: saved,
+        addOrEditContact: async (jid, info) => {
+            saved.push({ jid, name: info.fullName || "" });
+        },
+        name: "baileys",
+        isReady: () => true,
+        connect: async () => { },
+        disconnect: async () => { },
+        me: () => ({ id: "123@c.us" }),
+        sendText: async () => ({ id: "msg", chatId: "123@c.us", timestamp: Date.now() }),
+        sendImage: async () => ({ id: "img", chatId: "123@c.us", timestamp: Date.now() }),
+        sendVideo: async () => ({ id: "vid", chatId: "123@c.us", timestamp: Date.now() }),
+        sendAudio: async () => ({ id: "aud", chatId: "123@c.us", timestamp: Date.now() }),
+        sendDocument: async () => ({ id: "doc", chatId: "123@c.us", timestamp: Date.now() }),
+        sendSticker: async () => ({ id: "stk", chatId: "123@c.us", timestamp: Date.now() }),
+        sendLocation: async () => ({ id: "loc", chatId: "123@c.us", timestamp: Date.now() }),
+        sendContact: async () => ({ id: "cnt", chatId: "123@c.us", timestamp: Date.now() }),
+        sendReaction: async () => { },
+        sendPoll: async () => ({ id: "pll", chatId: "123@c.us", timestamp: Date.now() }),
+        react: async () => { },
+        deleteMessage: async () => { },
+        editMessage: async () => { },
+        sendPresenceUpdate: async () => { },
+        readMessages: async () => { },
+        onWhatsApp: async () => null,
+        getBusinessProfile: async () => null,
+        profilePictureUrl: async () => null,
+        fetchStatus: async () => null,
+        updateBlockStatus: async () => { },
+        removeContact: async () => { },
+        groupMetadata: async () => ({ subject: "Test Group", participants: [] }),
+        groupParticipantsUpdate: async () => [],
+        groupUpdateSubject: async () => { },
+        groupUpdateDescription: async () => { },
+        groupInviteCode: async () => "",
+        groupRevokeInvite: async () => "",
+        updateProfilePicture: async () => { },
+        updateProfileName: async () => { },
+        updateProfileStatus: async () => { },
+        downloadMedia: async () => null,
+        on: () => () => { },
+    };
+}
+describe("kernel/contactAutoSave", () => {
+    test("accumulates DM messages and triggers addOrEditContact when target reached", async () => {
+        const contract = createMockContract();
+        const jid = "5511999991111@c.us";
+        const msg = {
+            id: "1",
+            chatId: jid,
+            fromMe: false,
+            timestamp: Date.now(),
+            text: "hello",
+            pushName: "Alice",
+            raw: {},
+        };
+        // Send up to 6 DM messages (max target range is 3-6)
+        for (let i = 0; i < 6; i++) {
+            await trackIncomingForContactSave(contract, msg, jid, false, false);
+        }
+        assert.ok(contract.savedContacts.length > 0);
+        assert.equal(contract.savedContacts[0].name, "Alice");
+    });
+    test("ignores silent group messages (triggeredBot = false)", async () => {
+        const contract = createMockContract();
+        const jid = "5511999992222@c.us";
+        const msg = {
+            id: "2",
+            chatId: "group1@g.us",
+            fromMe: false,
+            timestamp: Date.now(),
+            text: "just chatting",
+            pushName: "Bob",
+            raw: {},
+        };
+        for (let i = 0; i < 10; i++) {
+            await trackIncomingForContactSave(contract, msg, jid, true, false);
+        }
+        assert.equal(contract.savedContacts.length, 0);
+    });
+});

package/dist/kernel/driverManager.js

@@ -11,12 +11,7 @@
  * globalSock in pluginLoader.ts. Only main.ts is expected to call
  * register(); everywhere else reads through active() / get() / isDegraded.
  *
- * Shutdown order in shutdown() is reverse-registration, so a driver
- * that was added later (e.g. whatsmeow) is disconnected before the
- * primary one (typically Baileys). Re-registering the same name
- * overwrites the previous instance — the old driver is NOT disconnected
- * automatically, callers must disconnect it first if they want it torn
- * down.
+ * Shutdown order in shutdown() is reverse-registration.
  *
  * See the interface and cooldown semantics.
  */
@@ -69,6 +64,15 @@ class DriverManager {
     markDegraded(name, durationMs) {
         this.degradedUntil.set(name, Date.now() + durationMs);
     }
+    /**
+     * Drop the degradation entry for `name` so the next `isDegraded()`
+     * check returns false. Used after a successful send to clear the
+     * cooldown that the most recent failed send had set, without waiting
+     * for the timer to expire.
+     */
+    clearDegraded(name) {
+        this.degradedUntil.delete(name);
+    }
     /**
      * Promote a different driver to active. Used by tests / hot-swap;
      * the production sendFallbackGuard never calls this — fallback uses

package/dist/kernel/driverManager.test.js

@@ -0,0 +1,90 @@
+import test, { describe, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import { getDriverManager, _resetDriverManagerForTests } from "#kernel/driverManager.js";
+function createFakeDriver(name, ready = true) {
+    const state = { disconnected: false };
+    const mockRef = (id) => ({ id, chatId: "123@c.us", timestamp: Date.now() });
+    return {
+        name,
+        isReady: () => ready,
+        disconnect: async () => {
+            state.disconnected = true;
+        },
+        get disconnected() {
+            return state.disconnected;
+        },
+        connect: async () => { },
+        me: () => ({ id: "123@c.us" }),
+        sendText: async () => mockRef("msg1"),
+        sendImage: async () => mockRef("msg2"),
+        sendVideo: async () => mockRef("msg3"),
+        sendAudio: async () => mockRef("msg4"),
+        sendSticker: async () => mockRef("msg5"),
+        sendDocument: async () => mockRef("msg6"),
+        sendLocation: async () => mockRef("msg7"),
+        sendContact: async () => mockRef("msg8"),
+        sendReaction: async () => { },
+        sendPoll: async () => mockRef("msg9"),
+        react: async () => { },
+        deleteMessage: async () => { },
+        editMessage: async () => { },
+        sendPresenceUpdate: async () => { },
+        readMessages: async () => { },
+        onWhatsApp: async () => null,
+        getBusinessProfile: async () => null,
+        profilePictureUrl: async () => null,
+        fetchStatus: async () => null,
+        updateBlockStatus: async () => { },
+        addOrEditContact: async () => { },
+        removeContact: async () => { },
+        groupMetadata: async () => ({ subject: "Test Group", participants: [] }),
+        groupParticipantsUpdate: async () => [],
+        groupUpdateSubject: async () => { },
+        groupUpdateDescription: async () => { },
+        groupInviteCode: async () => "",
+        groupRevokeInvite: async () => "",
+        updateProfilePicture: async () => { },
+        updateProfileName: async () => { },
+        updateProfileStatus: async () => { },
+        downloadMedia: async () => null,
+        getContact: async () => null,
+        getProfilePictureUrl: async () => null,
+        on: () => () => { },
+    };
+}
+describe("kernel/driverManager", () => {
+    beforeEach(() => {
+        _resetDriverManagerForTests();
+    });
+    test("registers driver and returns active instance", () => {
+        const dm = getDriverManager();
+        const baileys = createFakeDriver("baileys");
+        dm.register(baileys, { isPrimary: true });
+        assert.equal(dm.activeName_(), "baileys");
+        assert.equal(dm.active(), baileys);
+        assert.equal(dm.get("baileys"), baileys);
+        assert.equal(dm.isReady("baileys"), true);
+    });
+    test("throws if active() called with no drivers registered", () => {
+        const dm = getDriverManager();
+        assert.throws(() => dm.active(), /no active driver registered/);
+    });
+    test("tracks degradation with expiration", async (t) => {
+        t.mock.timers.enable({ apis: ["Date"] });
+        const dm = getDriverManager();
+        const baileys = createFakeDriver("baileys");
+        dm.register(baileys, { isPrimary: true });
+        assert.equal(dm.isDegraded("baileys"), false);
+        dm.markDegraded("baileys", 1000);
+        assert.equal(dm.isDegraded("baileys"), true);
+        t.mock.timers.tick(1001);
+        assert.equal(dm.isDegraded("baileys"), false);
+    });
+    test("shutdown disconnects all drivers", async () => {
+        const dm = getDriverManager();
+        const baileys = createFakeDriver("baileys");
+        dm.register(baileys, { isPrimary: true });
+        await dm.shutdown();
+        assert.equal(baileys.disconnected, true);
+    });
+});

package/dist/kernel/integrationMode.js

@@ -0,0 +1,88 @@
+/**
+ * kernel/integrationMode.ts
+ *
+ * Toggles the "integration" mode that gates the WhatsApp integration
+ * test suite. In integration mode the bot loads a private plugin
+ * (`__manybot_integration__`) whose job is to drive real-WhatsApp
+ * operations from the test harness, and refuse to act in any chat
+ * other than the configured `TEST_CHAT`.
+ *
+ * Activation requires BOTH signals (mirrors `testConfig`):
+ *   - `MANYBOT_RUN_WHATSAPP_TESTS=1`  (explicit opt-in)
+ *   - a configured `TEST_CHAT`        (env or manybot.toml)
+ *
+ * Production code never imports this module in its hot path. The
+ * integration plugin loader is the only consumer; the production bot
+ * does not load the integration plugin and is not affected by the
+ * opt-in flag.
+ *
+ * The reserved plugin name uses a `__manybot_*__` double-underscore
+ * pattern so it cannot collide with a real plugin (the loader's
+ * normal `~/.manybot/plugins/<name>/` path does not create a
+ * directory starting with `__` on user machines, and the test setup
+ * installs it into a separate, non-user-controlled location).
+ */
+import path from "path";
+import { getTestConfig, requireTestConfig } from "#kernel/testConfig.js";
+import { logger } from "#logger";
+/**
+ * Reserved plugin name. The leading and trailing `__` are
+ * deliberate: this name is documented as reserved by the runtime,
+ * so no real plugin directory should ever be created with it.
+ * Plugins loaded from `~/.manybot/plugins/` with names that match
+ * this pattern are NOT auto-loaded by `loadPlugins()`; the
+ * integration harness has to ask for them explicitly.
+ */
+export const INTEGRATION_PLUGIN_NAME = "__manybot_integration__";
+/**
+ * Absolute path to the integration plugin's source directory inside
+ * the project. The plugin ships with the repo (not with the user's
+ * `~/.manybot/plugins/`) and is loaded directly from `src/`.
+ *
+ * Resolved relative to this module so the path survives the build
+ * (the plugin source is part of the published `src/` tree today;
+ * if/when the integration plugin gets moved into `dist/`, only
+ * this single constant needs to change).
+ */
+const INTEGRATION_PLUGIN_DIR = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..", "plugins", INTEGRATION_PLUGIN_NAME);
+/** True only when the operator has set the explicit opt-in flag. */
+export function isIntegrationOptIn() {
+    return process.env.MANYBOT_RUN_WHATSAPP_TESTS === "1";
+}
+export async function getIntegrationModeStatus() {
+    const cfg = await getTestConfig();
+    if (!isIntegrationOptIn()) {
+        return {
+            ready: false,
+            reason: `MANYBOT_RUN_WHATSAPP_TESTS=1 is required to enable integration mode`,
+            chat: cfg.chat,
+            source: cfg.source,
+        };
+    }
+    if (cfg.chat === null) {
+        return {
+            ready: false,
+            reason: cfg.skipReason,
+            chat: null,
+            source: null,
+        };
+    }
+    return { ready: true, reason: null, chat: cfg.chat, source: cfg.source };
+}
+/**
+ * Hard version: throws if integration mode is not fully ready. Use
+ * this at the entry point of every test that touches the real bot.
+ */
+export async function requireIntegrationMode() {
+    if (!isIntegrationOptIn()) {
+        throw new Error(`[integrationMode] cannot run: MANYBOT_RUN_WHATSAPP_TESTS=1 is required. ` +
+            `Set it explicitly to opt in to the real-WhatsApp test suite.`);
+    }
+    const cfg = await requireTestConfig();
+    logger.info(`[integrationMode] enabled — chat=${cfg.chat} source=${cfg.source}`);
+    return { chat: cfg.chat, source: cfg.source };
+}
+/** Absolute path of the integration plugin's source directory. */
+export function getIntegrationPluginDir() {
+    return INTEGRATION_PLUGIN_DIR;
+}

package/dist/kernel/integrationMode.test.js

@@ -0,0 +1,95 @@
+import test, { describe, before, after, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import fs from "fs/promises";
+import os from "os";
+import path from "path";
+const configDir = await fs.mkdtemp(path.join(os.tmpdir(), "manybot-integration-mode-"));
+process.env.MANYBOT_CONFIG_DIR = configDir;
+const { getIntegrationModeStatus, requireIntegrationMode, isIntegrationOptIn, INTEGRATION_PLUGIN_NAME, getIntegrationPluginDir, } = await import("#kernel/integrationMode.js");
+const { _resetTestConfigForTests, TEST_CHAT_ENV, RUN_WHATSAPP_TESTS_ENV, } = await import("#kernel/testConfig.js");
+const tomlPath = path.join(configDir, "manybot.toml");
+function clearEnv() {
+    delete process.env[TEST_CHAT_ENV];
+    delete process.env[RUN_WHATSAPP_TESTS_ENV];
+    delete process.env.MANYBOT_RUN_WHATSAPP_TESTS;
+}
+before(async () => {
+    await fs.writeFile(tomlPath, "", "utf8");
+});
+beforeEach(async () => {
+    clearEnv();
+    await fs.writeFile(tomlPath, "", "utf8");
+    _resetTestConfigForTests();
+});
+after(async () => {
+    clearEnv();
+    await fs.rm(configDir, { recursive: true, force: true });
+});
+describe("kernel/integrationMode — isIntegrationOptIn", () => {
+    test("false when env is unset", () => {
+        assert.equal(isIntegrationOptIn(), false);
+    });
+    test("false when env is anything other than '1'", () => {
+        process.env.MANYBOT_RUN_WHATSAPP_TESTS = "true";
+        assert.equal(isIntegrationOptIn(), false);
+        process.env.MANYBOT_RUN_WHATSAPP_TESTS = "0";
+        assert.equal(isIntegrationOptIn(), false);
+    });
+    test("true only when env equals '1'", () => {
+        process.env.MANYBOT_RUN_WHATSAPP_TESTS = "1";
+        assert.equal(isIntegrationOptIn(), true);
+    });
+});
+describe("kernel/integrationMode — getIntegrationModeStatus", () => {
+    test("not ready when opt-in is missing (even with TEST_CHAT set)", async () => {
+        process.env[TEST_CHAT_ENV] = "5516000000001";
+        const status = await getIntegrationModeStatus();
+        assert.equal(status.ready, false);
+        assert.match(status.reason, /MANYBOT_RUN_WHATSAPP_TESTS=1/);
+        assert.equal(status.chat, "5516000000001@s.whatsapp.net");
+    });
+    test("not ready when TEST_CHAT is missing (even with opt-in)", async () => {
+        process.env.MANYBOT_RUN_WHATSAPP_TESTS = "1";
+        const status = await getIntegrationModeStatus();
+        assert.equal(status.ready, false);
+        assert.match(status.reason, /TEST_CHAT is not set/);
+        assert.equal(status.chat, null);
+    });
+    test("ready only when both opt-in and TEST_CHAT are configured", async () => {
+        process.env[TEST_CHAT_ENV] = "5516000000002";
+        process.env.MANYBOT_RUN_WHATSAPP_TESTS = "1";
+        const status = await getIntegrationModeStatus();
+        assert.equal(status.ready, true);
+        assert.equal(status.reason, null);
+        assert.equal(status.chat, "5516000000002@s.whatsapp.net");
+        assert.equal(status.source, "env");
+    });
+});
+describe("kernel/integrationMode — requireIntegrationMode", () => {
+    test("returns chat and source when ready", async () => {
+        process.env[TEST_CHAT_ENV] = "5516000000003";
+        process.env.MANYBOT_RUN_WHATSAPP_TESTS = "1";
+        const res = await requireIntegrationMode();
+        assert.equal(res.chat, "5516000000003@s.whatsapp.net");
+        assert.equal(res.source, "env");
+    });
+    test("throws when opt-in is missing", async () => {
+        process.env[TEST_CHAT_ENV] = "5516000000004";
+        await assert.rejects(requireIntegrationMode(), /MANYBOT_RUN_WHATSAPP_TESTS=1/);
+    });
+    test("throws when TEST_CHAT is missing", async () => {
+        process.env.MANYBOT_RUN_WHATSAPP_TESTS = "1";
+        await assert.rejects(requireIntegrationMode(), /TEST_CHAT is not set/);
+    });
+});
+describe("kernel/integrationMode — constants", () => {
+    test("integration plugin name is reserved (double-underscore)", () => {
+        assert.equal(INTEGRATION_PLUGIN_NAME, "__manybot_integration__");
+        assert.ok(INTEGRATION_PLUGIN_NAME.startsWith("__"));
+        assert.ok(INTEGRATION_PLUGIN_NAME.endsWith("__"));
+    });
+    test("integration plugin dir resolves under src/plugins/", () => {
+        const dir = getIntegrationPluginDir();
+        assert.ok(dir.endsWith(path.join("src", "plugins", "__manybot_integration__")));
+    });
+});