@manybot/manybot 5.7.0 → 5.8.0

package/dist/kernel/statusServer.js

@@ -11,11 +11,17 @@ let status = {
     since: new Date().toISOString(),
 };
 export function setStatus(online, lastError) {
-    if (status.online === online)
+    // Same-state updates are a no-op for `online` / `since` so polling the
+    // status page doesn't see the timestamp flicker on every redundant
+    // call (the connection.update listener fires more than once per
+    // reconnect). An explicit `lastError` always wins — if the caller is
+    // reporting a new failure while we're already marked offline, that
+    // message is more useful than the stale one from before.
+    if (status.online === online && !lastError)
         return;
     status = {
         online,
-        since: new Date().toISOString(),
+        since: status.online === online ? status.since : new Date().toISOString(),
         ...(lastError ? { lastError } : {}),
     };
 }
@@ -36,4 +42,5 @@ export function startStatusServer(port) {
     server.listen(port, () => {
         logger.info(`[status] JSON endpoint em http://localhost:${port}`);
     });
+    return server;
 }

package/dist/kernel/statusServer.test.js

@@ -0,0 +1,70 @@
+import assert from "node:assert/strict";
+import { afterEach, describe, test } from "node:test";
+import { getStatus, setStatus, startStatusServer } from "#kernel/statusServer.js";
+describe("kernel/statusServer", () => {
+    let activeServer = null;
+    afterEach(async () => {
+        if (activeServer) {
+            await new Promise((resolve) => activeServer.close(() => resolve()));
+            activeServer = null;
+        }
+        // Reset status back to offline
+        setStatus(false);
+    });
+    test("getStatus returns initial state", () => {
+        const status = getStatus();
+        assert.equal(typeof status.online, "boolean");
+        assert.equal(typeof status.since, "string");
+    });
+    test("setStatus updates online state and timestamps", async () => {
+        setStatus(false, "Initial error");
+        const initial = getStatus();
+        assert.equal(initial.online, false);
+        assert.equal(initial.lastError, "Initial error");
+        // Allow timestamp to advance
+        await new Promise((r) => setTimeout(r, 10));
+        setStatus(true);
+        const updated = getStatus();
+        assert.equal(updated.online, true);
+        assert.equal(updated.lastError, undefined);
+        assert.notEqual(updated.since, initial.since);
+        // Setting same status is a no-op for since timestamp
+        const sinceBefore = updated.since;
+        setStatus(true);
+        assert.equal(getStatus().since, sinceBefore);
+    });
+    test("setStatus captures error message when going offline", () => {
+        setStatus(true);
+        setStatus(false, "Stream closed");
+        const status = getStatus();
+        assert.equal(status.online, false);
+        assert.equal(status.lastError, "Stream closed");
+    });
+    test("startStatusServer responds with JSON status and CORS headers", async () => {
+        setStatus(true);
+        activeServer = startStatusServer(0);
+        // Wait until the server is listening
+        await new Promise((resolve) => {
+            if (activeServer.listening)
+                resolve();
+            else
+                activeServer.once("listening", () => resolve());
+        });
+        const addr = activeServer.address();
+        const url = `http://127.0.0.1:${addr.port}/status`;
+        const res = await fetch(url);
+        assert.equal(res.status, 200);
+        assert.equal(res.headers.get("content-type"), "application/json");
+        assert.equal(res.headers.get("access-control-allow-origin"), "*");
+        const body = (await res.json());
+        assert.equal(body.online, true);
+        assert.equal(typeof body.since, "string");
+        assert.equal(body.lastError, undefined);
+        // Mutate status and verify dynamic response on subsequent request
+        setStatus(false, "Socket hung up");
+        const res2 = await fetch(url);
+        const body2 = (await res2.json());
+        assert.equal(body2.online, false);
+        assert.equal(body2.lastError, "Socket hung up");
+    });
+});

package/dist/kernel/testConfig.js

@@ -0,0 +1,183 @@
+/**
+ * kernel/testConfig.ts
+ *
+ * Reads the configuration that gates the WhatsApp integration test suite.
+ *
+ * Two values are exposed:
+ *
+ *   1. `chat` — the JID (or bare phone number) of the chat the integration
+ *      suite is allowed to exercise. Comes from, in precedence order:
+ *        a. environment variable `TEST_CHAT`
+ *        b. `TEST_CHAT` key in `manybot.toml`
+ *        c. otherwise absent (`chat === null`) — integration tests skip
+ *           with an explanatory message instead of crashing.
+ *
+ *   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
+ *      actually wants the integration suite to run.
+ *
+ * The module never throws on its own. `getTestConfig()` returns the
+ * resolved state and lets the caller decide what to do (skip vs run vs
+ * fail). `requireTestConfig()` is the hard version for code paths that
+ * must not run without a configured chat + opt-in.
+ *
+ * Deliberately kept out of `CONFIG` — `TEST_CHAT` is a test-time
+ * concern and shouldn't pollute the runtime config object's shape.
+ */
+import fs from "fs/promises";
+import { parse as parseToml } from "smol-toml";
+import { CONFIG_DIR, TOML_CONFIG_FILE } from "#config";
+import { logger } from "#logger";
+// ── Constants ───────────────────────────────────────────────────────────────
+/** Env var that signals "yes, the integration suite should really run". */
+export const RUN_WHATSAPP_TESTS_ENV = "MANYBOT_RUN_WHATSAPP_TESTS";
+/** Env var that overrides any value set in manybot.toml. */
+export const TEST_CHAT_ENV = "TEST_CHAT";
+/** Key read from manybot.toml as a fallback when the env var is unset. */
+export const TEST_CHAT_TOML_KEY = "TEST_CHAT";
+// ── JID normalization ──────────────────────────────────────────────────────
+/**
+ * Acceptable chat-id shapes:
+ *   - bare number:                 "5516999999999"
+ *   - WhatsApp PN JID:             "5516999999999@s.whatsapp.net"
+ *   - legacy framework PN JID:     "5516999999999@c.us"
+ *   - LID JID:                     "1234@lid"
+ *   - group JID:                   "120363…@g.us"
+ *
+ * Any other suffix is rejected so the integration plugin can rely on
+ * `chat.endsWith(...)` checks and not silently mismatch. Bare numbers
+ * are normalized to the WhatsApp PN JID form (the form the bot's own
+ * contract uses to reach that contact).
+ */
+export function normalizeTestChat(raw) {
+    if (typeof raw !== "string") {
+        throw new TypeError(`TEST_CHAT must be a string, got ${typeof raw}`);
+    }
+    const trimmed = raw.trim();
+    if (trimmed === "") {
+        throw new Error("TEST_CHAT is empty");
+    }
+    const ALLOWED_SUFFIXES = ["@s.whatsapp.net", "@c.us", "@lid", "@g.us"];
+    for (const suffix of ALLOWED_SUFFIXES) {
+        if (trimmed.endsWith(suffix)) {
+            const local = trimmed.slice(0, -suffix.length);
+            if (local === "" || /[^\dA-Za-z._-]/.test(local)) {
+                throw new Error(`TEST_CHAT has invalid local part: "${raw}"`);
+            }
+            return trimmed;
+        }
+    }
+    // Bare number — accept digits, plus, and the leading "+".
+    if (/^\+?\d+$/.test(trimmed)) {
+        return `${trimmed.replace(/^\+/, "")}@s.whatsapp.net`;
+    }
+    throw new Error(`TEST_CHAT must be a bare phone number or a JID with one of: ` +
+        `${ALLOWED_SUFFIXES.join(", ")} — got "${raw}"`);
+}
+// ── Resolution ──────────────────────────────────────────────────────────────
+async function readTomlTestChat() {
+    let raw;
+    try {
+        raw = await fs.readFile(TOML_CONFIG_FILE, "utf-8");
+    }
+    catch (e) {
+        if (e.code !== "ENOENT") {
+            logger.warn(`[testConfig] could not read ${TOML_CONFIG_FILE}: ${e.message}`);
+        }
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = parseToml(raw);
+    }
+    catch (e) {
+        logger.warn(`[testConfig] invalid TOML in ${TOML_CONFIG_FILE}: ${e.message}`);
+        return null;
+    }
+    const value = parsed[TEST_CHAT_TOML_KEY];
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== "string") {
+        logger.warn(`[testConfig] ${TEST_CHAT_TOML_KEY} in TOML is not a string, ignoring`);
+        return null;
+    }
+    return value.trim() === "" ? null : value;
+}
+let cached = null;
+/**
+ * Resolve the test configuration. Result is cached after the first call
+ * because the env and `manybot.toml` don't change mid-process; the
+ * cache gives every test a stable view without re-reading disk.
+ */
+export async function getTestConfig() {
+    if (cached)
+        return cached;
+    const envValue = process.env[TEST_CHAT_ENV];
+    let raw = null;
+    let source = null;
+    if (typeof envValue === "string" && envValue.trim() !== "") {
+        raw = envValue;
+        source = "env";
+    }
+    else {
+        const tomlValue = await readTomlTestChat();
+        if (tomlValue) {
+            raw = tomlValue;
+            source = "toml";
+        }
+    }
+    let chat = null;
+    if (raw !== null) {
+        try {
+            chat = normalizeTestChat(raw);
+        }
+        catch (e) {
+            logger.warn(`[testConfig] ${e.message}`);
+        }
+    }
+    const runWhatsApp = process.env[RUN_WHATSAPP_TESTS_ENV] === "1";
+    let skipReason = null;
+    if (chat === null) {
+        skipReason =
+            `TEST_CHAT is not set (env ${TEST_CHAT_ENV} or key ` +
+                `${TEST_CHAT_TOML_KEY} in ${TOML_CONFIG_FILE})`;
+    }
+    else if (!runWhatsApp) {
+        skipReason =
+            `${RUN_WHATSAPP_TESTS_ENV}=1 is required to run the WhatsApp ` +
+                `integration suite (TEST_CHAT alone is not enough)`;
+    }
+    cached = { chat, source, runWhatsApp, skipReason };
+    return cached;
+}
+/**
+ * Hard version of {@link getTestConfig}: throws if the chat is not
+ * configured or the opt-in flag is missing. Use this in code paths that
+ * should never run unless the operator has consciously opted in.
+ */
+export async function requireTestConfig() {
+    const cfg = await getTestConfig();
+    if (cfg.chat === null) {
+        throw new Error(`[testConfig] cannot run: ${cfg.skipReason}. ` +
+            `Set ${TEST_CHAT_ENV} or add '${TEST_CHAT_TOML_KEY} = "…"' to ${TOML_CONFIG_FILE}.`);
+    }
+    if (!cfg.runWhatsApp) {
+        throw new Error(`[testConfig] cannot run without opt-in: ${cfg.skipReason}. ` +
+            `Re-run with ${RUN_WHATSAPP_TESTS_ENV}=1.`);
+    }
+    return cfg;
+}
+/**
+ * Test-only — drops the cached value so the next `getTestConfig()`
+ * call re-reads env and disk. Use this after mutating env vars in a
+ * test; production code must not call it.
+ */
+export function _resetTestConfigForTests() {
+    cached = null;
+}
+// Keep `CONFIG_DIR` referenced so this module participates in the
+// project's path-resolution behavior the same way other kernel modules
+// do, and so future test fixtures that need to point at a different
+// config dir (e.g. MANYBOT_CONFIG_DIR) keep working.
+void CONFIG_DIR;

package/dist/kernel/testConfig.test.js

@@ -0,0 +1,181 @@
+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-test-config-"));
+process.env.MANYBOT_CONFIG_DIR = configDir;
+const { getTestConfig, requireTestConfig, normalizeTestChat, _resetTestConfigForTests, TEST_CHAT_ENV, RUN_WHATSAPP_TESTS_ENV, TEST_CHAT_TOML_KEY, } = await import("#kernel/testConfig.js");
+const { TOML_CONFIG_FILE } = await import("#config");
+const tomlPath = path.join(configDir, "manybot.toml");
+async function writeToml(contents) {
+    await fs.writeFile(tomlPath, contents, "utf8");
+}
+function clearEnv() {
+    delete process.env[TEST_CHAT_ENV];
+    delete process.env[RUN_WHATSAPP_TESTS_ENV];
+}
+before(async () => {
+    await fs.writeFile(tomlPath, "", "utf8");
+});
+beforeEach(async () => {
+    clearEnv();
+    await writeToml("");
+    _resetTestConfigForTests();
+});
+after(async () => {
+    clearEnv();
+    await fs.rm(configDir, { recursive: true, force: true });
+});
+describe("kernel/testConfig — normalizeTestChat", () => {
+    test("accepts a bare number and normalizes to @s.whatsapp.net", () => {
+        assert.equal(normalizeTestChat("5516999999999"), "5516999999999@s.whatsapp.net");
+    });
+    test("accepts a leading + on bare numbers", () => {
+        assert.equal(normalizeTestChat("+5516999999999"), "5516999999999@s.whatsapp.net");
+    });
+    test("preserves @c.us", () => {
+        assert.equal(normalizeTestChat("5516999999999@c.us"), "5516999999999@c.us");
+    });
+    test("preserves @s.whatsapp.net", () => {
+        assert.equal(normalizeTestChat("5516999999999@s.whatsapp.net"), "5516999999999@s.whatsapp.net");
+    });
+    test("preserves @lid", () => {
+        assert.equal(normalizeTestChat("12345@lid"), "12345@lid");
+    });
+    test("preserves @g.us", () => {
+        assert.equal(normalizeTestChat("120363012345678@g.us"), "120363012345678@g.us");
+    });
+    test("trims surrounding whitespace", () => {
+        assert.equal(normalizeTestChat("  5516999999999  "), "5516999999999@s.whatsapp.net");
+    });
+    test("rejects empty string", () => {
+        assert.throws(() => normalizeTestChat(""), /empty/);
+    });
+    test("rejects non-string input", () => {
+        assert.throws(() => normalizeTestChat(undefined), /string/);
+    });
+    test("rejects unknown suffix", () => {
+        assert.throws(() => normalizeTestChat("foo@example.com"), /JID/);
+    });
+    test("rejects JID with bad chars in the local part", () => {
+        assert.throws(() => normalizeTestChat("5516!@c.us"), /local part/);
+    });
+});
+describe("kernel/testConfig — getTestConfig", () => {
+    test("returns null chat and skipReason when nothing is configured", async () => {
+        const cfg = await getTestConfig();
+        assert.equal(cfg.chat, null);
+        assert.equal(cfg.source, null);
+        assert.equal(cfg.runWhatsApp, false);
+        assert.match(cfg.skipReason, /TEST_CHAT is not set/);
+    });
+    test("env wins over TOML", async () => {
+        await writeToml(`${TEST_CHAT_TOML_KEY} = "5516000000001"\n`);
+        process.env[TEST_CHAT_ENV] = "5516000000002";
+        const cfg = await getTestConfig();
+        assert.equal(cfg.chat, "5516000000002@s.whatsapp.net");
+        assert.equal(cfg.source, "env");
+    });
+    test("falls back to TOML when env is unset", async () => {
+        await writeToml(`${TEST_CHAT_TOML_KEY} = "5516000000003"\n`);
+        const cfg = await getTestConfig();
+        assert.equal(cfg.chat, "5516000000003@s.whatsapp.net");
+        assert.equal(cfg.source, "toml");
+    });
+    test("empty string in TOML is treated as absent", async () => {
+        await writeToml(`${TEST_CHAT_TOML_KEY} = ""\n`);
+        const cfg = await getTestConfig();
+        assert.equal(cfg.chat, null);
+    });
+    test("whitespace-only env is treated as absent", async () => {
+        process.env[TEST_CHAT_ENV] = "   ";
+        const cfg = await getTestConfig();
+        assert.equal(cfg.chat, null);
+    });
+    test("invalid value in TOML is ignored (warning logged, not thrown)", async () => {
+        await writeToml(`${TEST_CHAT_TOML_KEY} = "not-a-valid-jid@x.com"\n`);
+        const cfg = await getTestConfig();
+        assert.equal(cfg.chat, null);
+    });
+    test("non-string TOML value is ignored", async () => {
+        await writeToml(`${TEST_CHAT_TOML_KEY} = 42\n`);
+        const cfg = await getTestConfig();
+        assert.equal(cfg.chat, null);
+    });
+    test("runWhatsApp is true only when env equals '1'", async () => {
+        process.env[TEST_CHAT_ENV] = "5516000000004";
+        process.env[RUN_WHATSAPP_TESTS_ENV] = "1";
+        const on = await getTestConfig();
+        assert.equal(on.runWhatsApp, true);
+        _resetTestConfigForTests();
+        process.env[RUN_WHATSAPP_TESTS_ENV] = "true";
+        const off1 = await getTestConfig();
+        assert.equal(off1.runWhatsApp, false);
+        _resetTestConfigForTests();
+        process.env[RUN_WHATSAPP_TESTS_ENV] = "0";
+        const off2 = await getTestConfig();
+        assert.equal(off2.runWhatsApp, false);
+        _resetTestConfigForTests();
+        delete process.env[RUN_WHATSAPP_TESTS_ENV];
+        const off3 = await getTestConfig();
+        assert.equal(off3.runWhatsApp, false);
+    });
+    test("skipReason explains the missing opt-in even when TEST_CHAT is set", async () => {
+        await writeToml(`${TEST_CHAT_TOML_KEY} = "5516000000005"\n`);
+        const cfg = await getTestConfig();
+        assert.equal(cfg.chat, "5516000000005@s.whatsapp.net");
+        assert.equal(cfg.runWhatsApp, false);
+        assert.match(cfg.skipReason, /MANYBOT_RUN_WHATSAPP_TESTS=1/);
+    });
+    test("skipReason is null when everything is configured", async () => {
+        process.env[TEST_CHAT_ENV] = "5516000000006";
+        process.env[RUN_WHATSAPP_TESTS_ENV] = "1";
+        const cfg = await getTestConfig();
+        assert.equal(cfg.skipReason, null);
+    });
+    test("result is cached across calls within the same process", async () => {
+        process.env[TEST_CHAT_ENV] = "5516000000007";
+        const first = await getTestConfig();
+        process.env[TEST_CHAT_ENV] = "5516000000008";
+        const second = await getTestConfig();
+        assert.equal(first.chat, second.chat, "cache must not re-read env");
+        _resetTestConfigForTests();
+        const third = await getTestConfig();
+        assert.equal(third.chat, "5516000000008@s.whatsapp.net");
+    });
+    test("missing manybot.toml is treated as 'no value'", async () => {
+        await fs.rm(tomlPath, { force: true });
+        const cfg = await getTestConfig();
+        assert.equal(cfg.chat, null);
+        assert.equal(cfg.source, null);
+    });
+    test("malformed TOML is logged and treated as 'no value'", async () => {
+        await fs.writeFile(tomlPath, "this is not valid = = toml =", "utf8");
+        const cfg = await getTestConfig();
+        assert.equal(cfg.chat, null);
+    });
+});
+describe("kernel/testConfig — requireTestConfig", () => {
+    test("returns config when fully configured", async () => {
+        process.env[TEST_CHAT_ENV] = "5516000000009";
+        process.env[RUN_WHATSAPP_TESTS_ENV] = "1";
+        const cfg = await requireTestConfig();
+        assert.equal(cfg.chat, "5516000000009@s.whatsapp.net");
+        assert.equal(cfg.runWhatsApp, true);
+    });
+    test("throws when TEST_CHAT is missing", async () => {
+        process.env[RUN_WHATSAPP_TESTS_ENV] = "1";
+        await assert.rejects(requireTestConfig(), /TEST_CHAT is not set/);
+    });
+    test("throws when opt-in is missing", async () => {
+        process.env[TEST_CHAT_ENV] = "5516000000010";
+        await assert.rejects(requireTestConfig(), /MANYBOT_RUN_WHATSAPP_TESTS=1/);
+    });
+});
+// smoke: TOML_CONFIG_FILE should point inside the temp config dir
+describe("kernel/testConfig — wiring", () => {
+    test("TOML_CONFIG_FILE respects MANYBOT_CONFIG_DIR", () => {
+        assert.equal(TOML_CONFIG_FILE, tomlPath);
+    });
+});

package/dist/kernel/updateCheck.js

@@ -2,13 +2,19 @@
  * updateCheck.ts
  *
  * Compares the locally installed manybot version against the latest
- * published on npm, and fires an "info" alert (via alerts.ts) when a
+ * GitHub Release and fires an "info" alert (via alerts.ts) when a
  * newer version is available. Runs once on startup and then on a
  * schedule — both configurable (UPDATE_CHECK_ENABLED,
  * UPDATE_CHECK_INTERVAL_HOURS).
  *
- * Never throws — a failed check (offline, npm down) is logged at debug
- * level and silently skipped; it'll just try again next cycle.
+ * GitHub Releases is the source of truth for distribution: release
+ * candidate tags (-rc.N) skip npm entirely, and stable releases stay
+ * in "staged" on npm until a manual 2FA approval lands, so reading
+ * registry.npmjs.org here would either miss an already-published
+ * version or notify about one only after a long delay.
+ *
+ * Never throws — a failed check (offline, GitHub down) is logged at
+ * debug level and silently skipped; it'll just try again next cycle.
  */
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
@@ -16,10 +22,11 @@ import path from "path";
 import { UPDATE_CHECK_ENABLED, UPDATE_CHECK_INTERVAL_HOURS } from "#config";
 import { sendAlert } from "#kernel/alerts.js";
 import { logger } from "#logger";
+import { t } from "#i18n";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const pkg = JSON.parse(readFileSync(path.join(__dirname, "../../package.json"), "utf8"));
-const REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(pkg.name)}/latest`;
+const GITHUB_RELEASES_LATEST = "https://api.github.com/repos/many-bot/manybot/releases/latest";
 /** Naive semver compare — good enough for x.y.z, no pre-release handling. */
 function isNewer(latest, current) {
     const a = latest.split(".").map(Number);
@@ -34,6 +41,14 @@ function isNewer(latest, current) {
     }
     return false;
 }
+/**
+ * GitHub tags come prefixed with "v" (e.g. "v5.7.0"). Strip it so we
+ * can compare against pkg.version directly and render the upgrade
+ * command without the prefix.
+ */
+function stripTagPrefix(tag) {
+    return tag.startsWith("v") ? tag.slice(1) : tag;
+}
 let alreadyNotifiedFor = null;
 /**
  * Runs a single check. Safe to call anytime (startup, interval, manual
@@ -43,23 +58,31 @@ export async function checkForUpdate() {
     if (!UPDATE_CHECK_ENABLED)
         return;
     try {
-        const res = await fetch(REGISTRY_URL);
+        const res = await fetch(GITHUB_RELEASES_LATEST);
         if (!res.ok) {
-            logger.debug(`[updateCheck] npm registry responded ${res.status}`);
+            logger.debug(`[updateCheck] GitHub Releases responded ${res.status}`);
             return;
         }
         const data = await res.json();
-        const latest = data.version;
-        if (!latest || !isNewer(latest, pkg.version))
+        const rawTag = data.tag_name;
+        if (!rawTag)
+            return;
+        const latest = stripTagPrefix(rawTag);
+        if (!isNewer(latest, pkg.version))
             return;
         // Don't re-alert every cycle for the same version once already notified.
         if (alreadyNotifiedFor === latest)
             return;
         alreadyNotifiedFor = latest;
+        const releaseUrl = `https://github.com/many-bot/manybot/releases/tag/${rawTag}`;
         await sendAlert({
             level: "info",
-            title: "Nova versão do manybot disponível",
-            message: `Instalada: ${pkg.version} → disponível: ${latest}. Rode "npm install -g ${pkg.name}@${latest}" (ou equivalente) para atualizar.`,
+            title: t("alerts.updateAvailableTitle"),
+            message: t("alerts.updateAvailableMessage", {
+                installed: pkg.version,
+                available: latest,
+                url: releaseUrl,
+            }),
         });
     }
     catch (e) {

package/dist/locales/en.json

@@ -36,13 +36,75 @@
     "cacheLoaded": "{{count}} chat(s) loaded from cache.",
     "cacheLoadedStale": "{{count}} chat(s) loaded from cache (stale).",
     "sendFailedNoFallback": "manybot: no fallback driver available (jid={{jid}}, primary={{driver}})",
-    "sendFailedBothDrivers": "manybot: send failed on both drivers (jid={{jid}}, tried={{primary}} then {{secondary}})"
+    "sendFailedBothDrivers": "manybot: send failed on both drivers (jid={{jid}}, tried={{primary}} then {{secondary}})",
+    "commandsConfigMissingCmd": "commands.yaml: command \"{{id}}\" is missing required field \"cmd\" — skipped",
+    "commandRegistryInvalidPluginCommand": "commandRegistry: plugin \"{{plugin}}\" command \"{{function}}\" ({{id}}) has an invalid or missing \"cmd\" — skipped",
+    "commandsConfigArgumentMissingName": "commands.yaml: argument entry under \"{{id}}\" is missing required field \"name\" — skipped",
+    "commandsConfigArgumentMissingType": "commands.yaml: argument \"{{name}}\" under \"{{id}}\" is missing required field \"type\" — skipped",
+    "commandsConfigUnknownArgType": "commands.yaml: argument \"{{name}}\" under \"{{id}}\" has unknown type \"{{type}}\" — skipped",
+    "commandsConfigChoiceArgumentNoChoices": "commands.yaml: argument \"{{name}}\" under \"{{id}}\" is type \"choice\" but declared no choices — falling back to free placeholder in usage",
+    "commandsConfigArgumentsNotList": "commands.yaml: arguments under \"{{id}}\" must be a list — ignored",
+    "commandsConfigSubcommandMissingCmd": "commands.yaml: subcommand under \"{{id}}\" is missing required field \"cmd\" — skipped",
+    "commandsConfigSubcommandsNotList": "commands.yaml: subcommands under \"{{id}}\" must be a list — ignored",
+    "commandsConfigDuplicateSubcommand": "commands.yaml: duplicate subcommand \"{{cmd}}\" under \"{{id}}\" — keeping the first one",
+    "commandsConfigReadFailed": "commands.yaml: could not be read ({{path}}): {{message}}",
+    "commandsConfigParseFailed": "commands.yaml: YAML parse error: {{message}}",
+    "commandsConfigInvalidRoot": "commands.yaml: top-level must be a map of command entries",
+    "commandsConfigInvalidEntry": "commands.yaml: entry \"{{id}}\" is not an object — skipped",
+    "commandsConfigImportReadFailed": "commands.yaml: import \"{{path}}\" could not be read: {{message}}",
+    "commandsConfigImportParseFailed": "commands.yaml: import \"{{path}}\" YAML parse error: {{message}}",
+    "commandsConfigImportInvalidRoot": "commands.yaml: import \"{{path}}\" top-level must be a map of sections — skipped",
+    "commandsConfigImportNested": "commands.yaml: import \"{{path}}\" declares its own \"import\" — nested imports are not supported and were ignored",
+    "commandsConfigImportKeyConflict": "commands.yaml: import \"{{path}}\" redefines \"{{key}}\", already owned by \"{{owner}}\" — keeping the first one",
+    "commandRegistryOrphanEntry": "commandRegistry: entry \"{{id}}\" targets {{plugin}}.{{function}} but no active plugin provides it — skipped",
+    "commandRegistryInvalidEntry": "commandRegistry: entry \"{{id}}\" has no plugin/function and no text — skipped",
+    "commandRegistryInvocationCollision": "commandRegistry: invocation \"{{text}}\" already owned by \"{{winner}}\" — dropping {{loser}} ({{via}})",
+    "commandDeprecationRenamed": "commandRegistry: command \"{{id}}\" renamed from \"{{old}}\" to \"{{new}}\" — notifying old callers for {{days}} days",
+    "commandDeprecationRemoved": "commandRegistry: command \"{{id}}\" (cmd \"{{old}}\") was removed — notifying old callers for {{days}} days",
+    "commandDeprecationFallbackRenamed": "Command \"{{old}}\" was renamed to \"{{new}}\". Please update your message.",
+    "commandDeprecationFallbackRemoved": "Command \"{{old}}\" is no longer available.",
+    "commandDeprecationReservedInvocation": "commandRegistry: invocation \"{{text}}\" is reserved by active deprecation for \"{{id}}\" — refusing registration",
+    "commandManualMissing": "No detailed manual available for command \"{{cmd}}\".",
+    "commandNotFound": "Command or category \"{{cmd}}\" not found. Use {{prefix}}{{menuCmd}} to view the command list.",
+    "commandRegistryMenuAliasCollision": "commandRegistry: menu alias \"{{alias}}\" collided with real command \"{{winner}}\" — menu alias ignored"
   },
   "errors": {
     "stack": "Stack",
     "invalid_config": "Invalid config file {{file}}: {{error}}",
     "fix_config": "Fix the syntax in {{file}} before starting the bot."
   },
+  "menu": {
+    "intro": "Use {prefix}<command> to run it or {prefix}help <command> to view its manual.",
+    "other": "Other",
+    "category": "Category",
+    "manual": "Manual",
+    "description": "Description"
+  },
+  "commandPermissions": {
+    "botNotAdmin": "This command requires the bot to be a group administrator.",
+    "senderNotAdmin": "This command is restricted to group administrators.",
+    "ownerOnly": "This command can only be run by the bot owner.",
+    "wrongScope": "This command cannot be used in this context.",
+    "cooldown": "Wait {{seconds}}s before using this command again."
+  },
+  "commandRun": {
+    "missingRequiredArg": "Missing required argument(s).",
+    "unknownSubcommand": "Unknown subcommand \"{{sub}}\" for !{{cmd}}. Valid: {{valid}}."
+  },
+  "alerts": {
+    "noFallbackTitle": "manybot: no fallback driver",
+    "bothDriversFailedTitle": "manybot: sending failed on both drivers",
+    "updateAvailableTitle": "New manybot version available",
+    "updateAvailableMessage": "Installed: {{installed}} → available: {{available}}. See {{url}} for update instructions.",
+    "reconnectHaltedTitle": "manybot stopped reconnecting",
+    "reconnectHaltedMessage": "Gave up after {{attempts}} attempts — possible account restriction. Run connect() manually to retry."
+  },
+  "driver": {
+    "groupParticipantNotFound": "\"{{id}}\" does not match a current participant in group \"{{group}}\" (check whether the person is still in the group, or use a reply/mention instead of typing the number).",
+    "groupParticipantsUpdateRejected": "groupParticipantsUpdate(\"{{action}}\") rejected for: {{detail}}",
+    "groupParticipantsUpdateFailed": "groupParticipantsUpdate(\"{{action}}\") failed for group \"{{group}}\" with participants [{{users}}]: {{message}}",
+    "pollDecryptFailed": "Failed to decrypt poll vote: {{error}}"
+  },
   "onboarding": {
     "intro": "ManyBot — first login",
     "methodPrompt": "How do you want to connect your WhatsApp account?",
@@ -69,17 +131,6 @@
     "retrying": "Retrying ({{attempt}}/{{max}})...",
     "sessionWiped": "Session discarded, pairing again ({{round}}/{{max}})...",
     "connectGaveUp": "Couldn't connect after several attempts. Check your network and try again."
-  },
-  "whatsmeow": {
-    "installPrompt": "Install whatsmeow driver for fallback support? (EXPERIMENTAL — only text send & history work; other methods throw)",
-    "unsupportedArch": "whatsmeow driver not available for {{os}}-{{arch}}. The bot will use Baileys only.",
-    "fetchingTag": "Fetching latest whatsmeow release...",
-    "fetchFailed": "Could not reach Codeberg. Skipping whatsmeow install.",
-    "downloading": "Downloading {{url}}...",
-    "downloadFailed": "Download failed: {{reason}}",
-    "installTitle": "whatsmeow driver",
-    "installed": "whatsmeow driver installed at {{path}}",
-    "restartNotice": "Restart the bot for the whatsmeow driver to take effect.",
-    "experimentalNotice": "whatsmeow is EXPERIMENTAL: only sendText and getHistory are implemented. sendImage, sendPoll, groupMetadata, and other methods throw."
   }
 }
+