@manybot/manybot 5.2.0 → 5.2.1

package/dist/kernel/pluginGuard.js

@@ -0,0 +1,88 @@
+/**
+ * pluginGuard.ts
+ *
+ * Runs a plugin safely.
+ *
+ * Protections:
+ *   - Hard timeout per plugin run (prevents infinite hangs from locking the queue)
+ *   - Catches and logs all errors with structured context
+ *   - Marks errored plugins so they are silently skipped from then on
+ *   - Never crashes the bot
+ *
+ * Per-plugin overrides:
+ *   Plugins may export a `guardOptions` object to opt out of specific
+ *   protections. The pluginLoader is responsible for reading this export
+ *   and storing it as `plugin.guardOptions` in the registry entry.
+ *
+ *   Supported keys:
+ *     timeout {boolean}  — set to `false` to disable the hard timeout.
+ *                          Use only for plugins that intentionally block
+ *                          (e.g. heavy media processing, sticker generation).
+ */
+import { logger } from "#logger";
+import { pluginRegistry } from "#kernel/pluginLoader.js";
+/** Max ms a single plugin run is allowed to take before it's force-aborted. */
+const PLUGIN_TIMEOUT_MS = 120_000;
+/**
+ * Races `promise` against a timeout rejection.
+ * @param {Promise}  promise
+ * @param {number}   ms
+ * @param {string}   pluginName
+ */
+function withTimeout(promise, ms, pluginName) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`[${pluginName}] timed out after ${ms}ms`)), ms);
+    });
+    return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+/**
+ * @param {object} plugin   — pluginRegistry entry
+ * @param {object} context  — buildApi ctx
+ *
+ * plugin.guardOptions (optional, read from plugin's own export):
+ *   @param {boolean} [plugin.guardOptions.timeout=true]
+ */
+export async function runPlugin(plugin, context) {
+    if (plugin.status !== "active")
+        return;
+    const useTimeout = plugin.guardOptions?.timeout !== false;
+    try {
+        if (!plugin.run)
+            return;
+        const run = plugin.run(context);
+        await (useTimeout ? withTimeout(run, PLUGIN_TIMEOUT_MS, plugin.name) : run);
+    }
+    catch (e) {
+        const error = e instanceof Error ? e : new Error(String(e));
+        const errorCount = (plugin.errorCount ?? 0) + 1;
+        plugin.errorCount = errorCount;
+        plugin.error = error;
+        const isTimeout = useTimeout && error.message?.startsWith("timed out");
+        if (errorCount >= 3) {
+            plugin.status = "error";
+            pluginRegistry.set(plugin.name, plugin);
+            logger.error(`[pluginGuard] Plugin "${plugin.name}" threw an error and has failed 3 times. Disabling plugin.`);
+            logger.error(`  message : ${error.message}`);
+            if (!isTimeout) {
+                const frame = error.stack?.split("\n")[1]?.trim() ?? "(no stack)";
+                logger.error(`  at      : ${frame}`);
+            }
+        }
+        else {
+            pluginRegistry.set(plugin.name, plugin);
+            logger.warn(`[pluginGuard] Plugin "${plugin.name}" threw an error (attempt ${errorCount}/3). Reloading...`);
+            logger.warn(`  message : ${error.message}`);
+            if (!isTimeout) {
+                const frame = error.stack?.split("\n")[1]?.trim() ?? "(no stack)";
+                logger.warn(`  at      : ${frame}`);
+            }
+            // Reload the plugin dynamically to avoid circular dependency
+            import("#kernel/pluginLoader.js").then(({ reloadPlugin }) => {
+                reloadPlugin(plugin.name).catch(err => {
+                    logger.error(`[pluginGuard] Failed to reload plugin "${plugin.name}": ${err.message}`);
+                });
+            });
+        }
+    }
+}

package/dist/kernel/pluginLoader.js

@@ -0,0 +1,322 @@
+/**
+ * pluginLoader.ts
+ *
+ * Responsible for:
+ *   1. Reading active plugins (config.ts imports this module and give the list)
+ *   2. Loading each plugin from ~/.manybot/plugins folder
+ *   3. Registering in pluginRegistry with status and public exports
+ *   4. Exposing pluginRegistry to kernel and pluginApi
+ *   5. Watching plugin files and config file for hot reloading
+ */
+import fs from "fs";
+import path from "path";
+import { logger } from "#logger";
+import { t } from "#i18n";
+import { pathToFileURL } from "url";
+import { PATHS } from "#config";
+import { buildSetupApi, cleanupPluginEvents } from "#manyapi";
+const PLUGINS_DIR = path.join(PATHS.HOME, "plugins");
+export const pluginRegistry = new Map();
+let globalSock = null;
+let globalStore = null;
+const pluginWatchers = new Map();
+let configWatcher = null;
+/**
+ * Load all active plugins listed in `activePlugins`.
+ * Called once during bot initialization.
+ *
+ * @param {string[]} activePlugins — active plugin names
+ */
+export async function loadPlugins(activePlugins) {
+    if (!fs.existsSync(PLUGINS_DIR)) {
+        fs.mkdirSync(PLUGINS_DIR, { recursive: true });
+    }
+    for (const name of activePlugins) {
+        await loadPlugin(name);
+    }
+    startConfigWatcher();
+    const total = pluginRegistry.size;
+    const active = [...pluginRegistry.values()].filter(p => p.status === "active").length;
+    const errors = total - active;
+    logger.success(t("system.pluginsLoaded", {
+        count: active,
+        errors: errors ? t("system.pluginsLoadedWithErrors", { count: errors }) : ""
+    }));
+}
+/**
+ * Call setup(api) on all plugins that export it.
+ * Executed once after bot connects.
+ */
+export async function setupPlugins(sock, store) {
+    globalSock = sock;
+    globalStore = store;
+    for (const plugin of pluginRegistry.values()) {
+        if (plugin.status !== "active" || !plugin.setup)
+            continue;
+        try {
+            const api = buildSetupApi(sock, store, pluginRegistry, plugin.name);
+            await plugin.setup(api);
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            logger.error(t("system.pluginSetupFailed", {
+                name: plugin.name,
+                message: err.message
+            }));
+        }
+    }
+}
+async function findPluginPath(name) {
+    const dir = path.join(PLUGINS_DIR, name);
+    const manifest = path.join(dir, "manyplug.json");
+    if (!fs.existsSync(manifest))
+        return null;
+    const data = JSON.parse(await fs.promises.readFile(manifest, "utf8"));
+    const candidates = [
+        data.main,
+        "index.js",
+        "index.ts"
+    ].filter((v) => typeof v === "string" &&
+        v.trim().length > 0);
+    for (const file of candidates) {
+        const entry = path.join(dir, file);
+        if (fs.existsSync(entry))
+            return entry;
+    }
+    return null;
+}
+/**
+ * Load a single plugin by name.
+ * @param {string} name
+ * @param {boolean} isReload
+ */
+export async function loadPlugin(name, isReload = false) {
+    const pluginPath = await findPluginPath(name);
+    const existing = pluginRegistry.get(name);
+    const errorCount = existing ? (existing.errorCount ?? 0) : 0;
+    if (!pluginPath) {
+        logger.warn(t("system.pluginNotFound", { name, path: path.join(PLUGINS_DIR, name) }));
+        pluginRegistry.set(name, {
+            name,
+            status: "disabled",
+            run: null,
+            setup: null,
+            exports: null,
+            error: null,
+            guardOptions: {},
+            errorCount: 0
+        });
+        unwatchPlugin(name);
+        return;
+    }
+    if (!fs.existsSync(pluginPath)) {
+        logger.warn(t("system.pluginNotFound", { name, path: pluginPath }));
+        pluginRegistry.set(name, {
+            name,
+            status: "disabled",
+            run: null,
+            setup: null,
+            exports: null,
+            error: null,
+            guardOptions: {},
+            errorCount: 0
+        });
+        unwatchPlugin(name);
+        return;
+    }
+    try {
+        const importUrl = pathToFileURL(pluginPath).href + (isReload ? `?update=${Date.now()}` : "");
+        const mod = await import(importUrl);
+        // Plugin must export a default function — this is called on every message
+        if (typeof mod.default !== "function") {
+            throw new Error(`Plugin "${name}" does not export a default function`);
+        }
+        pluginRegistry.set(name, {
+            name,
+            status: "active",
+            run: mod.default,
+            setup: mod.setup ?? null,
+            exports: mod.api ?? null,
+            error: null,
+            guardOptions: mod.guardOptions ?? {},
+            errorCount: 0,
+        });
+        logger.info(t(isReload ? "system.pluginReloaded" : "system.pluginLoaded", { name }));
+        watchPluginDirectory(name);
+    }
+    catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        logger.error(t("system.pluginLoadFailed", { name, message: err.message }));
+        const newErrorCount = isReload ? (errorCount + 1) : 3;
+        pluginRegistry.set(name, {
+            name,
+            status: newErrorCount >= 3 ? "error" : "active",
+            run: null,
+            setup: null,
+            exports: null,
+            error: err,
+            guardOptions: {},
+            errorCount: newErrorCount,
+        });
+    }
+}
+/**
+ * Reload a single plugin dynamically.
+ */
+export async function reloadPlugin(name) {
+    const plugin = pluginRegistry.get(name);
+    if (!plugin)
+        return;
+    if (globalSock) {
+        cleanupPluginEvents(name, globalSock);
+    }
+    await loadPlugin(name, true);
+    const updatedPlugin = pluginRegistry.get(name);
+    if (updatedPlugin && updatedPlugin.status === "active" && updatedPlugin.setup && globalSock && globalStore) {
+        try {
+            const api = buildSetupApi(globalSock, globalStore, pluginRegistry, name);
+            await updatedPlugin.setup(api);
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            logger.error(`[pluginLoader] Setup failed during reload for "${name}": ${err.message}`);
+            const newErrorCount = (updatedPlugin.errorCount ?? 0) + 1;
+            updatedPlugin.errorCount = newErrorCount;
+            updatedPlugin.error = err;
+            if (newErrorCount >= 3) {
+                updatedPlugin.status = "error";
+                logger.error(`[pluginLoader] Plugin "${name}" failed setup 3 times and was disabled.`);
+            }
+            else {
+                logger.warn(`[pluginLoader] Retrying reload for "${name}" (setup error, attempt ${newErrorCount}/3)`);
+                reloadPlugin(name).catch(() => { });
+            }
+        }
+    }
+}
+/**
+ * Sync active plugins based on config file updates.
+ */
+export async function syncPlugins() {
+    const oldActive = new Set([...pluginRegistry.entries()]
+        .filter(([_, p]) => p.status === "active")
+        .map(([name]) => name));
+    const { reloadConfig, PLUGINS } = await import("#config");
+    await reloadConfig();
+    const newActive = new Set(PLUGINS);
+    // Disable plugins that were removed from config
+    for (const name of oldActive) {
+        if (!newActive.has(name)) {
+            logger.info(`[pluginLoader] Disabling plugin "${name}"`);
+            const plugin = pluginRegistry.get(name);
+            if (plugin) {
+                if (globalSock) {
+                    cleanupPluginEvents(name, globalSock);
+                }
+                plugin.status = "disabled";
+                unwatchPlugin(name);
+            }
+        }
+    }
+    // Enable/load plugins that were added to config
+    for (const name of newActive) {
+        if (!oldActive.has(name)) {
+            logger.info(`[pluginLoader] Enabling plugin "${name}"`);
+            await loadPlugin(name);
+            const plugin = pluginRegistry.get(name);
+            if (plugin && plugin.status === "active" && plugin.setup && globalSock && globalStore) {
+                try {
+                    const api = buildSetupApi(globalSock, globalStore, pluginRegistry, name);
+                    await plugin.setup(api);
+                }
+                catch (e) {
+                    const err = e instanceof Error ? e : new Error(String(e));
+                    logger.error(`[pluginLoader] Setup failed for newly enabled plugin "${name}": ${err.message}`);
+                }
+            }
+        }
+    }
+}
+/**
+ * Watch a plugin's directory for changes.
+ */
+export function watchPluginDirectory(name) {
+    if (pluginWatchers.has(name))
+        return;
+    const dir = path.join(PLUGINS_DIR, name);
+    if (!fs.existsSync(dir))
+        return;
+    try {
+        let watchTimeout = null;
+        const watcher = fs.watch(dir, { recursive: true }, (eventType, filename) => {
+            if (watchTimeout)
+                clearTimeout(watchTimeout);
+            watchTimeout = setTimeout(async () => {
+                logger.info(`[watcher] Plugin "${name}" file change detected (${filename}). Reloading...`);
+                await reloadPlugin(name);
+            }, 500);
+        });
+        pluginWatchers.set(name, watcher);
+    }
+    catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        logger.warn(`[watcher] Failed to watch plugin "${name}" directory: ${err.message}`);
+    }
+}
+/**
+ * Stop watching a plugin's directory.
+ */
+export function unwatchPlugin(name) {
+    const watcher = pluginWatchers.get(name);
+    if (watcher) {
+        watcher.close();
+        pluginWatchers.delete(name);
+    }
+}
+/**
+ * Watch the config directory for manyplug.toml or manybot.toml changes.
+ */
+function startConfigWatcher() {
+    if (configWatcher)
+        return;
+    try {
+        let configTimeout = null;
+        configWatcher = fs.watch(PATHS.HOME, (eventType, filename) => {
+            if (filename === "manyplug.toml" || filename === "manybot.toml") {
+                if (configTimeout)
+                    clearTimeout(configTimeout);
+                configTimeout = setTimeout(async () => {
+                    logger.info(`[watcher] Config file change detected: ${filename}. Syncing plugins...`);
+                    await syncPlugins();
+                }, 500);
+            }
+        });
+    }
+    catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        logger.warn(`[watcher] Failed to start config directory watcher: ${err.message}`);
+    }
+}
+export async function cleanupPlugins() {
+    if (configWatcher) {
+        configWatcher.close();
+        configWatcher = null;
+    }
+    for (const [name, watcher] of pluginWatchers.entries()) {
+        watcher.close();
+    }
+    pluginWatchers.clear();
+    for (const plugin of pluginRegistry.values()) {
+        try {
+            const evts = plugin.exports?.["events"];
+            await evts?.["cleanup"]?.();
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            logger.error(t("system.pluginCleanupFailed", {
+                name: plugin.name,
+                message: err.message
+            }));
+        }
+    }
+}

package/dist/kernel/scheduler.js

@@ -0,0 +1,110 @@
+/**
+ * scheduler.ts
+ *
+ * Allows plugins to register scheduled tasks via cron.
+ * Uses node-cron underneath, but plugins never import node-cron directly —
+ * they only call ctx.scheduler.schedule(cron, fn).
+ *
+ * Registrations are deduped per (pluginName, expression) and persisted to
+ * disk so a hot-reload never stacks duplicate crons, and a restart doesn't
+ * silently lose track of what each plugin previously scheduled. Plugins
+ * still need to call schedule() again on boot/setup — functions can't be
+ * serialized — but doing so now replaces the old entry instead of adding
+ * a new one, and getPersisted() lets the kernel/log confirm what survived.
+ *
+ * Usage in plugin:
+ *   export default async function (ctx) {
+ *     ctx.scheduler.schedule("0 9 * * 1", async () => {
+ *       await ctx.send.text("Good morning!");
+ *     });
+ *   }
+ */
+import cron from "node-cron";
+import Database from "better-sqlite3";
+import path from "path";
+import { mkdirSync } from "fs";
+import { logger } from "#logger";
+import { t } from "#i18n";
+import { CONFIG_DIR } from "#config";
+// key = `${pluginName}::${expression}`
+const tasks = new Map();
+// ── Persistence (metadata only — fn can't be serialized) ────────────────────
+mkdirSync(CONFIG_DIR, { recursive: true });
+const db = new Database(path.join(CONFIG_DIR, "scheduler.db"));
+db.pragma("journal_mode = WAL");
+db.exec(`
+  CREATE TABLE IF NOT EXISTS scheduled_tasks (
+    plugin_name  TEXT NOT NULL,
+    expression   TEXT NOT NULL,
+    updated_at   INTEGER NOT NULL DEFAULT (unixepoch()),
+    PRIMARY KEY  (plugin_name, expression)
+  );
+`);
+const stmtUpsert = db.prepare(`INSERT INTO scheduled_tasks (plugin_name, expression) VALUES (?, ?)
+   ON CONFLICT(plugin_name, expression) DO UPDATE SET updated_at = unixepoch()`);
+const stmtDeleteOne = db.prepare(`DELETE FROM scheduled_tasks WHERE plugin_name = ? AND expression = ?`);
+const stmtDeletePlugin = db.prepare(`DELETE FROM scheduled_tasks WHERE plugin_name = ?`);
+const stmtAll = db.prepare(`SELECT plugin_name, expression FROM scheduled_tasks`);
+/** Rows persisted from previous runs — for diagnostics/logging on boot. */
+export function getPersisted() {
+    return stmtAll.all().map(r => ({
+        pluginName: r.plugin_name,
+        expression: r.expression,
+    }));
+}
+// ── Scheduling ────────────────────────────────────────────────────────────
+/**
+ * Register a cron task.
+ * Calling this again with the same (pluginName, expression) replaces the
+ * previous task instead of stacking a new one — this is what fixed the
+ * unbounded leak on plugin reload.
+ *
+ * @param {string}   expression  — cron expression e.g., "0 9 * * 1"
+ * @param {Function} fn          — async function to execute
+ * @param {string}   pluginName  — plugin name (for logging/scoping)
+ */
+export function schedule(expression, fn, pluginName = "unknown") {
+    if (!cron.validate(expression)) {
+        logger.warn(t("system.schedulerInvalidCron", { name: pluginName, expression }));
+        return { stop() { } };
+    }
+    const key = `${pluginName}::${expression}`;
+    tasks.get(key)?.task.stop();
+    const task = cron.schedule(expression, async () => {
+        try {
+            await fn();
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            logger.error(t("system.schedulerError", { name: pluginName, message: err.message }));
+        }
+    });
+    tasks.set(key, { pluginName, expression, task });
+    stmtUpsert.run(pluginName, expression);
+    logger.info(t("system.schedulerRegistered", { name: pluginName, expression }));
+    return {
+        stop() {
+            if (tasks.get(key)?.task !== task)
+                return; // already replaced/stopped
+            task.stop();
+            tasks.delete(key);
+            stmtDeleteOne.run(pluginName, expression);
+        },
+    };
+}
+/** Stop and forget every task registered by one plugin (reload/unload). */
+export function cancelPlugin(pluginName) {
+    for (const [key, entry] of tasks) {
+        if (entry.pluginName !== pluginName)
+            continue;
+        entry.task.stop();
+        tasks.delete(key);
+    }
+    stmtDeletePlugin.run(pluginName);
+}
+/** Stop all schedules in memory (process shutdown) — keeps persisted rows. */
+export function stopAll() {
+    for (const { task } of tasks.values())
+        task.stop();
+    tasks.clear();
+}

package/dist/kernel/sendGuard.js

@@ -0,0 +1,121 @@
+/**
+ * sendGuard.ts
+ *
+ * Anti-detection throttle layer for all outbound sends.
+ *
+ * Three protections applied before every message:
+ *   1. Global token bucket  — hard cap on messages/second across all chats
+ *   2. Per-chat cooldown    — minimum gap between sends to the same chat
+ *   3. Human jitter         — random delay to break robotic timing patterns
+ *
+ * Text sends simulate the typing/recording presence indicator before
+ * the message arrives, so the chat shows "typing..." realistically.
+ */
+import { logger } from "#logger";
+// ── Tunables ──────────────────────────────────────────────────────────────────
+const GLOBAL_MSG_PER_SEC = 5;
+const CHAT_COOLDOWN_MS = 150;
+const JITTER_MS = { min: 50, max: 200 };
+const TYPING_CPS = 90;
+const TYPING_MAX_MS = 2000;
+const MEDIA_INDICATOR_MS = { min: 400, max: 1000 };
+// ── Global token bucket ───────────────────────────────────────────────────────
+const MS_PER_TOKEN = 1000 / GLOBAL_MSG_PER_SEC;
+let tokens = GLOBAL_MSG_PER_SEC;
+let lastRefill = Date.now();
+function consumeGlobalToken() {
+    const now = Date.now();
+    const elapsed = now - lastRefill;
+    tokens = Math.min(GLOBAL_MSG_PER_SEC, tokens + elapsed / MS_PER_TOKEN);
+    lastRefill = now;
+    if (tokens >= 1) {
+        tokens -= 1;
+        return 0;
+    }
+    return Math.ceil((1 - tokens) * MS_PER_TOKEN);
+}
+// ── Per-chat cooldown ─────────────────────────────────────────────────────────
+const lastSentAt = new Map();
+function chatCooldownMs(jid) {
+    const wait = (lastSentAt.get(jid) ?? 0) + CHAT_COOLDOWN_MS - Date.now();
+    return wait > 0 ? wait : 0;
+}
+function recordSend(jid) {
+    lastSentAt.set(jid, Date.now());
+}
+// ── Helpers ───────────────────────────────────────────────────────────────────
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+function randomJitter() {
+    return JITTER_MS.min + Math.random() * (JITTER_MS.max - JITTER_MS.min);
+}
+/**
+ * How long the typing indicator should appear before sending text.
+ * @param {string} text
+ * @returns {number} ms
+ */
+export function typingDuration(text) {
+    if (typeof text !== "string" || text.length === 0)
+        return 0;
+    return Math.min((text.length / TYPING_CPS) * 1000, TYPING_MAX_MS);
+}
+/**
+ * A human-feeling duration for media "processing" indicator.
+ * @returns {number} ms
+ */
+export function mediaDuration() {
+    return MEDIA_INDICATOR_MS.min
+        + Math.random() * (MEDIA_INDICATOR_MS.max - MEDIA_INDICATOR_MS.min);
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Wait for a safe send slot: global rate → per-chat cooldown → jitter.
+ * Must be called before every outbound message.
+ *
+ * @param {string}  jid
+ * @param {object}  [opts]
+ * @param {boolean} [opts.cooldown=true]
+ * @param {boolean} [opts.jitter=true]
+ */
+export async function waitForSendSlot(jid, { cooldown = true, jitter = true } = {}) {
+    const tokenWait = consumeGlobalToken();
+    if (tokenWait > 0) {
+        logger.debug(`[sendGuard] global rate hit — queuing ${tokenWait}ms`);
+        await sleep(tokenWait);
+    }
+    if (cooldown) {
+        const coolWait = chatCooldownMs(jid);
+        if (coolWait > 0) {
+            logger.debug(`[sendGuard] chat cooldown (${jid}) — waiting ${coolWait}ms`);
+            await sleep(coolWait);
+        }
+    }
+    if (jitter)
+        await sleep(randomJitter());
+    recordSend(jid);
+}
+/**
+ * Show a presence indicator for `ms` milliseconds, then clear it.
+ * No-op on drivers without the "presence" capability. Best-effort —
+ * errors are swallowed.
+ *
+ * @param {PresenceCapable|null}   adapter
+ * @param {string|null}            chatId
+ * @param {number}                 ms
+ * @param {"typing"|"recording"}   [state="typing"]
+ */
+export async function simulateState(adapter, chatId, ms, state = "typing") {
+    if (!adapter || !chatId || ms <= 0)
+        return;
+    if (!adapter.capabilities.has("presence") || !adapter.setPresence)
+        return;
+    try {
+        // Adapter contract only knows "composing" — recording is a WhatsApp nuance
+        // collapsed here until a driver needs to distinguish it.
+        await adapter.setPresence(chatId, "composing");
+        await sleep(ms);
+        await adapter.setPresence(chatId, "paused");
+    }
+    catch (e) {
+        logger.debug(`[sendGuard] presence simulation failed (non-fatal): ${e.message}`);
+    }
+}