@manybot/manybot 5.7.0 → 5.9.0

package/dist/kernel/activeDriverSend.test.js

@@ -0,0 +1,89 @@
+import test, { describe, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import { sendActiveDriverText } from "#kernel/activeDriverSend.js";
+import { getDriverManager, _resetDriverManagerForTests } from "#kernel/driverManager.js";
+function createMockDriver(name, ready = true, failsSend = false) {
+    const mockRef = (id) => ({ id, chatId: "123@c.us", timestamp: Date.now() });
+    return {
+        name,
+        isReady: () => ready,
+        sendText: async (jid, text) => {
+            if (failsSend)
+                throw new Error(`${name} sendText failed`);
+            return mockRef(`msg_${name}`);
+        },
+        connect: async () => { },
+        disconnect: async () => { },
+        me: () => ({ id: "123@c.us" }),
+        sendImage: async () => mockRef("image"),
+        sendVideo: async () => mockRef("image"),
+        sendAudio: async () => mockRef("image"),
+        sendDocument: async () => mockRef("image"),
+        sendSticker: async () => mockRef("image"),
+        sendLocation: async () => mockRef("loc"),
+        sendContact: async () => mockRef("contact"),
+        sendReaction: async () => { },
+        sendPoll: async () => mockRef("poll"),
+        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,
+        on: () => () => { },
+    };
+}
+describe("kernel/activeDriverSend", () => {
+    beforeEach(() => {
+        _resetDriverManagerForTests();
+    });
+    test("delivers text via the active driver when healthy", async () => {
+        const dm = getDriverManager();
+        const driver = createMockDriver("baileys");
+        dm.register(driver, { isPrimary: true });
+        const ref = await sendActiveDriverText("5511999999999@c.us", "hello");
+        assert.equal(ref.id, "msg_baileys");
+    });
+    test("propagates error when the active driver fails to send", async () => {
+        const dm = getDriverManager();
+        const failingDriver = createMockDriver("baileys", true, true);
+        dm.register(failingDriver, { isPrimary: true });
+        await assert.rejects(async () => sendActiveDriverText("5511999999999@c.us", "failing send"), /baileys sendText failed/);
+    });
+    test("passes quoted and mentions options through to the driver", async () => {
+        const dm = getDriverManager();
+        let receivedOpts = null;
+        const driver = {
+            ...createMockDriver("baileys"),
+            sendText: async (_jid, _text, opts) => {
+                receivedOpts = opts;
+                return { id: "msg1", chatId: _jid, timestamp: Date.now() };
+            },
+        };
+        dm.register(driver, { isPrimary: true });
+        const quotedRef = { id: "orig-msg", remoteJid: "123@s.whatsapp.net", fromMe: false };
+        const ref = await sendActiveDriverText("5511999999999@c.us", "reply", { quoted: quotedRef, mentions: ["@user1"] });
+        assert.equal(ref.id, "msg1");
+        assert.deepStrictEqual(receivedOpts, { quoted: quotedRef, mentions: ["@user1"] });
+    });
+    test("throws when no driver is registered", async () => {
+        const dm = getDriverManager();
+        await assert.rejects(async () => sendActiveDriverText("5511999999999@c.us", "no driver"), /no active driver/i);
+    });
+});

package/dist/kernel/alerts.js

@@ -29,6 +29,7 @@ import { spawn } from "child_process";
 import nodemailer from "nodemailer";
 import { CONFIG_DIR, ADMIN_JID, SMTP_HOST, SMTP_PORT, SMTP_SEC, SMTP_USER, SMTP_PASS, SMTP_FROM, SMTP_TO, SMTP_INSECURE, } from "#config";
 import { logger } from "#logger";
+import { t } from "#i18n";
 const ALERTS_LOG_FILE = path.join(CONFIG_DIR, "alerts.log");
 let sockProvider = null;
 /**
@@ -160,25 +161,18 @@ export function fireAlert(kind, details = {}) {
     if (kind === "send_failed_no_fallback") {
         event = {
             level: "critical",
-            title: "manybot: sem driver de fallback",
+            title: t("alerts.noFallbackTitle"),
             message: `jid=${details.jid} primary=${details.primary}`,
         };
     }
     else if (kind === "send_failed_both_drivers") {
         event = {
             level: "critical",
-            title: "manybot: envio falhou nos dois drivers",
+            title: t("alerts.bothDriversFailedTitle"),
             message: `jid=${details.jid} ${details.primary}->${details.secondary}` +
                 (details.error ? ` error=${String(details.error)}` : ""),
         };
     }
-    else if (kind === "whatsmeow_subprocess_halted") {
-        event = {
-            level: "critical",
-            title: "manybot: subprocesso whatsmeow halted",
-            message: `fallback indisponível: ${details.reason ?? "unknown"} — bot segue só com Baileys`,
-        };
-    }
     else {
         event = {
             level: "warning",

package/dist/kernel/chatOverrides.js

@@ -0,0 +1,46 @@
+/**
+ * kernel/chatOverrides.ts
+ *
+ * Per-chat overrides for the bot's global command prefix and language,
+ * set via `!config prefixo` / `!config idioma` (see coreCommands.ts).
+ * Both are stored under the "core" plugin namespace in settingsDb —
+ * the same storage plugins use via `ctx.settings`, keyed by the same
+ * `normalizeJid(msg.chatId)` that `buildApi()` uses to scope
+ * `ctx.settings` — so a value written here is read back under the
+ * exact same key it was written under.
+ *
+ * Kept as a standalone leaf module (only #config, jid utils, and
+ * settingsDb as deps) so it can be imported from anywhere in the
+ * dispatch pipeline (api/index.ts, messageHandler.ts, runCommand.ts,
+ * coreCommands.ts) without risking an import cycle.
+ */
+import { getPluginSetting } from "./settingsDb.js";
+import { normalizeJid } from "#drivers/jid.js";
+import { CMD_PREFIX } from "#config";
+const CORE_PLUGIN = "core";
+/**
+ * Resolves the effective command prefix for a chat: the chat's saved
+ * override (`!config prefixo`) if one was set, else the global
+ * `CMD_PREFIX`.
+ *
+ * @param chatId - the *raw* chat id (e.g. `msg.chatId`), not yet
+ *   normalized — this function normalizes it itself so callers don't
+ *   have to know which normalization the settings layer expects.
+ */
+export function getChatPrefix(chatId) {
+    const override = getPluginSetting(CORE_PLUGIN, normalizeJid(chatId), "chat_prefix");
+    return typeof override === "string" && override.length > 0 ? override : CMD_PREFIX;
+}
+/**
+ * Resolves the effective language code for a chat: the chat's saved
+ * override (`!config idioma`) if one was set, else `undefined` so the
+ * caller can fall back to the global language (`getCurrentLang()` /
+ * plain `t()`).
+ *
+ * @param chatId - the *raw* chat id (e.g. `msg.chatId`); normalized
+ *   internally, same as {@link getChatPrefix}.
+ */
+export function getChatLocale(chatId) {
+    const override = getPluginSetting(CORE_PLUGIN, normalizeJid(chatId), "chat_locale");
+    return typeof override === "string" && override.length > 0 ? override : undefined;
+}

package/dist/kernel/chatOverrides.test.js

@@ -0,0 +1,59 @@
+import test, { describe, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { getChatPrefix, getChatLocale } from "#kernel/chatOverrides.js";
+import { buildSettingsApi } from "#kernel/settingsDb.js";
+import { CMD_PREFIX } from "#config";
+describe("kernel/chatOverrides", () => {
+    // Already in normalized form ("@c.us") so writes and reads use the
+    // exact same storage key without relying on normalizeJid to no-op.
+    const chatId = "5511977776666@c.us";
+    beforeEach(() => {
+        buildSettingsApi("core", chatId).deleteAll();
+    });
+    afterEach(() => {
+        buildSettingsApi("core", chatId).deleteAll();
+    });
+    describe("getChatPrefix", () => {
+        test("returns the global CMD_PREFIX when no override is set", () => {
+            assert.equal(getChatPrefix(chatId), CMD_PREFIX);
+        });
+        test("returns the chat's saved override once !config prefixo has set one", () => {
+            buildSettingsApi("core", chatId).set("chat_prefix", "#");
+            assert.equal(getChatPrefix(chatId), "#");
+        });
+        test("does not leak one chat's override into another chat", () => {
+            buildSettingsApi("core", chatId).set("chat_prefix", "#");
+            assert.equal(getChatPrefix("5511900000000@c.us"), CMD_PREFIX);
+        });
+        test("reads back a value written under the raw (non-normalized) wire jid form", () => {
+            // buildApi()/buildMessageContext() scope ctx.settings with
+            // normalizeJid(msg.chatId) — a raw "@s.whatsapp.net" jid (with a
+            // device suffix, as WhatsApp sends it) must normalize to the same
+            // key so a write from the live message path is visible here too.
+            const rawJid = "5511977776666:12@s.whatsapp.net";
+            buildSettingsApi("core", "5511977776666@c.us").set("chat_prefix", "$");
+            assert.equal(getChatPrefix(rawJid), "$");
+        });
+        test("falls back to the global prefix for a blank saved override", () => {
+            buildSettingsApi("core", chatId).set("chat_prefix", "");
+            assert.equal(getChatPrefix(chatId), CMD_PREFIX);
+        });
+    });
+    describe("getChatLocale", () => {
+        test("returns undefined when no override is set, so callers fall back to the global language", () => {
+            assert.equal(getChatLocale(chatId), undefined);
+        });
+        test("returns the chat's saved override once !config idioma has set one", () => {
+            buildSettingsApi("core", chatId).set("chat_locale", "es");
+            assert.equal(getChatLocale(chatId), "es");
+        });
+        test("does not leak one chat's override into another chat", () => {
+            buildSettingsApi("core", chatId).set("chat_locale", "es");
+            assert.equal(getChatLocale("5511900000000@c.us"), undefined);
+        });
+        test("falls back to undefined for a blank saved override", () => {
+            buildSettingsApi("core", chatId).set("chat_locale", "");
+            assert.equal(getChatLocale(chatId), undefined);
+        });
+    });
+});

package/dist/kernel/chatSession.js

@@ -0,0 +1,65 @@
+/**
+ * chatSession.ts
+ *
+ * Phase 7 of MANYBOT-6.md — exclusive chat session, kernel primitive.
+ *
+ * Prevents two plugins from running an interactive flow (a game, the
+ * figurinha timeout session, a music-download prompt, etc.) in the same
+ * chat at the same time. The kernel only owns the lock itself — WHO holds
+ * it and for how long. Everything about the session's own state (timeout,
+ * collected media, turn tracking, ...) stays entirely inside the owning
+ * plugin; `commands.yaml` only ever registers commands, never internal
+ * flow state.
+ *
+ * Deliberately NOT persisted (no settingsDb / SQLite): a session lock only
+ * makes sense for the lifetime of the running process — restarting the
+ * bot should never leave a chat stuck "locked" by a plugin that no longer
+ * remembers it opened one.
+ *
+ * many-ai's passive continuation window (its own multi-turn follow-up
+ * mechanism) is a separate category by design and never touches this
+ * lock — see the Phase 7 note in MANYBOT-6.md. This module does not
+ * special-case many-ai; it simply never gets called by it.
+ */
+const sessions = new Map();
+/**
+ * Attempts to open an exclusive session for `pluginName` in `chatId`.
+ * Returns `true` if the session is now held by `pluginName` — either it
+ * was free, or `pluginName` already held it (idempotent re-acquire, e.g.
+ * a plugin calling acquire() again on a later message of its own flow).
+ * Returns `false` if another plugin already holds the session.
+ */
+export function acquireSession(chatId, pluginName) {
+    const current = sessions.get(chatId);
+    if (current && current.pluginName !== pluginName) {
+        return false;
+    }
+    sessions.set(chatId, { pluginName, acquiredAt: current?.acquiredAt ?? Date.now() });
+    return true;
+}
+/**
+ * Releases the session in `chatId`, but only if it is currently held by
+ * `pluginName` — a plugin can never release a lock it doesn't own. No-op
+ * (returns `false`) if the chat has no session, or it's held by someone
+ * else.
+ */
+export function releaseSession(chatId, pluginName) {
+    const current = sessions.get(chatId);
+    if (!current || current.pluginName !== pluginName) {
+        return false;
+    }
+    sessions.delete(chatId);
+    return true;
+}
+/** Whether `chatId` currently has an open exclusive session (by anyone). */
+export function isSessionLocked(chatId) {
+    return sessions.has(chatId);
+}
+/** Which plugin currently holds the session in `chatId`, if any. */
+export function getSessionHolder(chatId) {
+    return sessions.get(chatId)?.pluginName ?? null;
+}
+/** Test-only: wipe all session state between tests. */
+export function __resetSessionsForTests() {
+    sessions.clear();
+}

package/dist/kernel/chatSession.test.js

@@ -0,0 +1,46 @@
+import assert from "node:assert/strict";
+import test, { describe, beforeEach } from "node:test";
+import { acquireSession, releaseSession, isSessionLocked, getSessionHolder, __resetSessionsForTests, } from "#kernel/chatSession.js";
+describe("kernel/chatSession — Phase 7 exclusive chat session", () => {
+    beforeEach(() => {
+        __resetSessionsForTests();
+    });
+    test("acquire on a free chat succeeds and locks it", () => {
+        assert.equal(acquireSession("chat1", "gamePlugin"), true);
+        assert.equal(isSessionLocked("chat1"), true);
+        assert.equal(getSessionHolder("chat1"), "gamePlugin");
+    });
+    test("a different plugin cannot acquire an already-held session", () => {
+        assert.equal(acquireSession("chat1", "gamePlugin"), true);
+        assert.equal(acquireSession("chat1", "figurinhaPlugin"), false);
+        assert.equal(getSessionHolder("chat1"), "gamePlugin", "holder unchanged");
+    });
+    test("the same plugin re-acquiring its own session is idempotent", () => {
+        assert.equal(acquireSession("chat1", "gamePlugin"), true);
+        assert.equal(acquireSession("chat1", "gamePlugin"), true);
+        assert.equal(getSessionHolder("chat1"), "gamePlugin");
+    });
+    test("release only works for the plugin that holds the session", () => {
+        acquireSession("chat1", "gamePlugin");
+        assert.equal(releaseSession("chat1", "figurinhaPlugin"), false, "wrong plugin cannot release");
+        assert.equal(isSessionLocked("chat1"), true, "still locked");
+        assert.equal(releaseSession("chat1", "gamePlugin"), true);
+        assert.equal(isSessionLocked("chat1"), false);
+        assert.equal(getSessionHolder("chat1"), null);
+    });
+    test("releasing a chat with no session is a no-op", () => {
+        assert.equal(releaseSession("neverLocked", "anyPlugin"), false);
+    });
+    test("sessions are independent per chat", () => {
+        assert.equal(acquireSession("chatA", "gamePlugin"), true);
+        assert.equal(acquireSession("chatB", "figurinhaPlugin"), true);
+        assert.equal(getSessionHolder("chatA"), "gamePlugin");
+        assert.equal(getSessionHolder("chatB"), "figurinhaPlugin");
+    });
+    test("a freed session can be acquired by a different plugin afterward", () => {
+        acquireSession("chat1", "gamePlugin");
+        releaseSession("chat1", "gamePlugin");
+        assert.equal(acquireSession("chat1", "figurinhaPlugin"), true);
+        assert.equal(getSessionHolder("chat1"), "figurinhaPlugin");
+    });
+});

package/dist/kernel/commandAccess.js

@@ -0,0 +1,66 @@
+/**
+ * kernel/commandAccess.ts
+ *
+ * ctx.commands — read-only registry queries exposed to plugins (Phase 2
+ * of MANYBOT-6.md). Lets a plugin check whether another command exists,
+ * or read its desc/manual, without ctx.plugins.require()'ing the owning
+ * plugin. Primary consumer: many-ai, so it can verify a command before
+ * mentioning it instead of hallucinating.
+ *
+ * Lookups are case-sensitive and unaliased-vs-aliased the same way
+ * resolveDispatch() and the menu-alias check in commandRegistry.ts are —
+ * keyed exactly as the command/alias was declared, no implicit
+ * lowercasing here.
+ */
+import { getCommandRegistry } from "./commandRegistry.js";
+import { resolveLocalizedString } from "./commandMenu.js";
+/**
+ * All lookups take an optional explicit `registry` (defaulting to the
+ * live singleton via `getCommandRegistry()`) so this module can be unit
+ * tested with `buildCommandRegistry(...)` directly, the same convention
+ * `commandMenu.ts`'s `renderOverview(registry, lang)` uses.
+ */
+function resolveEntry(registry, invocation) {
+    if (!registry)
+        return null;
+    const id = registry.byInvocation.get(invocation);
+    if (!id)
+        return null;
+    return registry.byId.get(id) ?? null;
+}
+/** Whether `invocation` (a cmd or alias) resolves to a registered command. */
+export function exists(invocation, registry = getCommandRegistry()) {
+    return resolveEntry(registry, invocation) !== null;
+}
+/** Localized short description for `invocation`, or null if unknown/unset. */
+export function desc(invocation, lang, registry = getCommandRegistry()) {
+    const entry = resolveEntry(registry, invocation);
+    if (!entry)
+        return null;
+    return resolveLocalizedString(entry.desc, lang);
+}
+/** Localized manual text for `invocation`, falling back to `desc`. */
+export function manual(invocation, lang, registry = getCommandRegistry()) {
+    const entry = resolveEntry(registry, invocation);
+    if (!entry)
+        return null;
+    return resolveLocalizedString(entry.manual, lang) ?? resolveLocalizedString(entry.desc, lang);
+}
+/** All registered top-level commands, one entry per stable id. */
+export function list(lang, registry = getCommandRegistry()) {
+    if (!registry)
+        return [];
+    return Array.from(registry.byId.values(), (entry) => ({
+        id: entry.id,
+        cmd: entry.cmd,
+        aliases: [...entry.aliases],
+        category: entry.category,
+        desc: resolveLocalizedString(entry.desc, lang),
+    }));
+}
+/** Whether `text` is one of the menu command's own aliases (e.g. "menu", "help"). */
+export function isMenuAlias(text, registry = getCommandRegistry()) {
+    if (!registry)
+        return false;
+    return registry.menuAliases.has(text);
+}

package/dist/kernel/commandAccess.test.js

@@ -0,0 +1,74 @@
+import test, { describe } from "node:test";
+import assert from "node:assert/strict";
+import { exists, desc, manual, list, isMenuAlias } from "#kernel/commandAccess.js";
+import { buildCommandRegistry, DEFAULT_MENU_CONFIG } from "#kernel/commandRegistry.js";
+function createTestRegistry() {
+    const plugins = new Map([
+        [
+            "utilPlugin",
+            {
+                name: "utilPlugin",
+                status: "active",
+                manifest: { name: "utilPlugin", version: "1.0.0" },
+                commands: {
+                    pingFn: {
+                        cmd: "ping",
+                        aliases: ["p"],
+                        desc: { pt: "Testa a latência", en: "Tests latency" },
+                        category: "utils",
+                        manual: "Uso: !ping",
+                    },
+                    infoFn: {
+                        cmd: "info",
+                        aliases: [],
+                        desc: "Informações do bot",
+                        category: "utils",
+                    },
+                },
+            },
+        ],
+    ]);
+    const categories = {
+        utils: { label: { pt: "Utilitários", en: "Utilities" }, order: 1 },
+    };
+    return buildCommandRegistry(null, plugins, undefined, { ...DEFAULT_MENU_CONFIG, enabled: true }, categories);
+}
+describe("kernel/commandAccess", () => {
+    test("exists() is true for cmd and alias, false for unknown", () => {
+        const registry = createTestRegistry();
+        assert.equal(exists("ping", registry), true);
+        assert.equal(exists("p", registry), true);
+        assert.equal(exists("nope", registry), false);
+    });
+    test("exists() returns false with no registry", () => {
+        assert.equal(exists("ping", null), false);
+    });
+    test("desc() resolves the localized string for the requested lang", () => {
+        const registry = createTestRegistry();
+        assert.equal(desc("ping", "pt", registry), "Testa a latência");
+        assert.equal(desc("ping", "en", registry), "Tests latency");
+        assert.equal(desc("info", "pt", registry), "Informações do bot");
+        assert.equal(desc("nope", "pt", registry), null);
+    });
+    test("manual() falls back to desc() when no manual is set", () => {
+        const registry = createTestRegistry();
+        assert.equal(manual("ping", "pt", registry), "Uso: !ping");
+        assert.equal(manual("info", "pt", registry), "Informações do bot");
+    });
+    test("list() returns one entry per command with resolved desc", () => {
+        const registry = createTestRegistry();
+        const items = list("pt", registry);
+        assert.equal(items.length, 2);
+        const ping = items.find((i) => i.cmd === "ping");
+        assert.ok(ping);
+        assert.deepEqual(ping?.aliases, ["p"]);
+        assert.equal(ping?.category, "utils");
+        assert.equal(ping?.desc, "Testa a latência");
+    });
+    test("isMenuAlias() checks the registry's menuAliases set", () => {
+        const registry = createTestRegistry();
+        assert.equal(isMenuAlias("help", registry), true);
+        assert.equal(isMenuAlias("menu", registry), true);
+        assert.equal(isMenuAlias("ping", registry), false);
+    });
+});

package/dist/kernel/commandDeprecation.js

@@ -0,0 +1,170 @@
+/**
+ * commandDeprecation.ts
+ *
+ * Tracks command cmd/alias rename and removal across registry rebuilds.
+ * Persists state in the same SQLite database used by settingsDb.ts (separate
+ * file-scope DatabaseSync handle — same DB_PATH is fine).
+ *
+ * Two tables:
+ *   command_cmd_history      — current known (id → cmd). Populated on every
+ *                              syncCommandHistory() call; first-time inserts
+ *                              are silent (no deprecation triggered).
+ *   command_deprecations     — old_cmd → deprecation row. Created on rename
+ *                              or removal; expires by `notify_until`.
+ *
+ * Lookup is by old_cmd text — expired rows are treated as absent (lazy
+ * filtering, no cleanup sweep here).
+ */
+import { DatabaseSync } from "node:sqlite";
+import path from "path";
+import { mkdirSync } from "fs";
+import { logger } from "#logger";
+import { t } from "#i18n";
+import { CONFIG_DIR } from "#config";
+const DB_PATH = process.env.NODE_ENV === "test" ? ":memory:" : path.join(CONFIG_DIR, "settings.db");
+if (DB_PATH !== ":memory:") {
+    mkdirSync(path.dirname(DB_PATH), { recursive: true });
+}
+const db = new DatabaseSync(DB_PATH);
+db.exec("PRAGMA journal_mode = WAL");
+db.exec(`
+  CREATE TABLE IF NOT EXISTS command_cmd_history (
+    id         TEXT PRIMARY KEY,
+    cmd        TEXT NOT NULL,
+    updated_at INTEGER NOT NULL DEFAULT (unixepoch())
+  );
+
+  CREATE TABLE IF NOT EXISTS command_deprecations (
+    old_cmd     TEXT PRIMARY KEY,
+    id          TEXT NOT NULL,
+    new_cmd     TEXT,
+    notify_until INTEGER NOT NULL,
+    message     TEXT
+  );
+`);
+const stmts = {
+    getHistoryCmd: db.prepare("SELECT cmd FROM command_cmd_history WHERE id = ?"),
+    insertHistory: db.prepare(`
+    INSERT INTO command_cmd_history (id, cmd, updated_at)
+    VALUES (?, ?, unixepoch())
+    ON CONFLICT (id)
+    DO UPDATE SET cmd = excluded.cmd, updated_at = excluded.updated_at
+  `),
+    deleteHistory: db.prepare("DELETE FROM command_cmd_history WHERE id = ?"),
+    allHistoryIds: db.prepare("SELECT id FROM command_cmd_history"),
+    getDeprecation: db.prepare("SELECT old_cmd, id, new_cmd, notify_until, message FROM command_deprecations WHERE old_cmd = ?"),
+    upsertDeprecation: db.prepare(`
+    INSERT INTO command_deprecations (old_cmd, id, new_cmd, notify_until, message)
+    VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT (old_cmd)
+    DO UPDATE SET id = excluded.id,
+                  new_cmd = excluded.new_cmd,
+                  notify_until = excluded.notify_until,
+                  message = excluded.message
+  `),
+};
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/**
+ * Reconcile the current registry `byId` against the persisted history.
+ *
+ * Per id:
+ *   - not in history → INSERT silently (first sighting, no notice).
+ *   - in history, same cmd → no-op.
+ *   - in history, different cmd → INSERT into command_deprecations with the
+ *     OLD cmd, new_cmd = new cmd, notify_until = now + period.
+ *
+ * Ids that vanished from byId → INSERT into command_deprecations with
+ * new_cmd = null, and DELETE the history row (the deprecation IS the record
+ * that the id is gone).
+ *
+ * `spec.notifyChanges ?? defaults.notifyChanges` controls whether any row
+ * is written for that id. When false, the history is still updated silently
+ * and no deprecation is recorded (admin-opt-out).
+ */
+export function syncCommandHistory(byId, defaults, specs) {
+    const specById = new Map(specs.map(s => [s.id, s]));
+    const now = Date.now();
+    for (const [id, entry] of byId) {
+        const spec = specById.get(id);
+        const notify = spec?.notifyChanges ?? defaults.notifyChanges;
+        const existing = stmts.getHistoryCmd.get(id);
+        const prevCmd = existing?.cmd ?? null;
+        if (prevCmd === null) {
+            stmts.insertHistory.run(id, entry.cmd);
+            continue;
+        }
+        if (prevCmd === entry.cmd)
+            continue;
+        if (notify) {
+            const periodMs = defaults.notifyPeriodDays * MS_PER_DAY;
+            stmts.upsertDeprecation.run(prevCmd, id, entry.cmd, now + periodMs, spec?.deprecatedMessage ?? null);
+            logger.warn(t("system.commandDeprecationRenamed", {
+                id,
+                old: prevCmd,
+                new: entry.cmd,
+                days: String(defaults.notifyPeriodDays)
+            }));
+        }
+        stmts.insertHistory.run(id, entry.cmd);
+    }
+    const currentIds = new Set(byId.keys());
+    const persistedIds = stmts.allHistoryIds.all().map(r => r.id);
+    for (const id of persistedIds) {
+        if (currentIds.has(id))
+            continue;
+        const existing = stmts.getHistoryCmd.get(id);
+        if (!existing)
+            continue;
+        const spec = specById.get(id);
+        const notify = spec?.notifyChanges ?? defaults.notifyChanges;
+        if (notify) {
+            const periodMs = defaults.notifyPeriodDays * MS_PER_DAY;
+            stmts.upsertDeprecation.run(existing.cmd, id, null, now + periodMs, spec?.deprecatedMessage ?? null);
+            logger.warn(t("system.commandDeprecationRemoved", {
+                id,
+                old: existing.cmd,
+                days: String(defaults.notifyPeriodDays)
+            }));
+        }
+        stmts.deleteHistory.run(id);
+    }
+}
+/**
+ * Returns the active deprecation row for `cmdText`, or null if there is no
+ * deprecation or it has already expired.
+ */
+export function getActiveDeprecation(cmdText) {
+    const row = stmts.getDeprecation.get(cmdText);
+    if (!row)
+        return null;
+    if (row.notify_until <= Date.now())
+        return null;
+    return row;
+}
+function interpolate(template, vars) {
+    return template.replace(/\{\{(\w+)\}\}/g, (_match, name) => Object.prototype.hasOwnProperty.call(vars, name) ? vars[name] : `{{${name}}}`);
+}
+/**
+ * Resolve the final user-facing message:
+ *   1. row.message (per-command override from yaml `deprecatedMessage`)
+ *   2. defaults.notifyMessage (global override)
+ *   3. built-in fallback ("Command \"{old}\" was renamed to \"{new}\"..." or
+ *      "Command \"{old}\" has been removed" for removals)
+ */
+export function formatDeprecationMessage(row, defaults) {
+    const vars = {
+        old: row.old_cmd,
+        new: row.new_cmd ?? "",
+        days: String(Math.max(0, Math.ceil((row.notify_until - Date.now()) / MS_PER_DAY))),
+    };
+    if (row.message && row.message.trim().length > 0) {
+        return interpolate(row.message, vars);
+    }
+    if (defaults.notifyMessage && defaults.notifyMessage.trim().length > 0) {
+        return interpolate(defaults.notifyMessage, vars);
+    }
+    const fallbackKey = row.new_cmd === null
+        ? "system.commandDeprecationFallbackRemoved"
+        : "system.commandDeprecationFallbackRenamed";
+    return interpolate(t(fallbackKey), vars);
+}