@manybot/manybot 5.7.0 → 5.8.0

package/dist/kernel/pluginGuard.js

@@ -36,22 +36,21 @@ function withTimeout(promise, ms, pluginName) {
     });
     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) {
+export async function runPlugin(plugin, context, handler, input, options) {
     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);
+        if (handler) {
+            const run = handler(context, input);
+            await (useTimeout ? withTimeout(run, PLUGIN_TIMEOUT_MS, plugin.name) : run);
+        }
+        else {
+            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));
@@ -68,6 +67,8 @@ export async function runPlugin(plugin, context) {
                 const frame = error.stack?.split("\n")[1]?.trim() ?? "(no stack)";
                 logger.error(`  at      : ${frame}`);
             }
+            if (options?.rethrow)
+                throw error;
         }
         else {
             pluginRegistry.set(plugin.name, plugin);
@@ -77,6 +78,8 @@ export async function runPlugin(plugin, context) {
                 const frame = error.stack?.split("\n")[1]?.trim() ?? "(no stack)";
                 logger.warn(`  at      : ${frame}`);
             }
+            if (options?.rethrow)
+                throw error;
             // Reload the plugin dynamically to avoid circular dependency
             import("#kernel/pluginLoader.js").then(({ reloadPlugin }) => {
                 reloadPlugin(plugin.name).catch(err => {

package/dist/kernel/pluginGuard.test.js

@@ -0,0 +1,39 @@
+import test, { describe } from "node:test";
+import assert from "node:assert/strict";
+import { runPlugin } from "#kernel/pluginGuard.js";
+describe("kernel/pluginGuard", () => {
+    test("runs handler successfully without modifying plugin error status", async () => {
+        const plugin = {
+            name: "safePlugin",
+            status: "active",
+            manifest: { name: "safePlugin", version: "1.0.0" },
+        };
+        let executed = false;
+        const handler = async () => {
+            executed = true;
+        };
+        await runPlugin(plugin, {}, handler);
+        assert.equal(executed, true);
+        assert.equal(plugin.status, "active");
+        assert.equal(plugin.errorCount ?? 0, 0);
+    });
+    test("tracks errorCount and disables plugin after 3 failures", async () => {
+        const plugin = {
+            name: "failingPlugin",
+            status: "active",
+            manifest: { name: "failingPlugin", version: "1.0.0" },
+        };
+        const failingHandler = async () => {
+            throw new Error("Crash");
+        };
+        await runPlugin(plugin, {}, failingHandler);
+        assert.equal(plugin.errorCount, 1);
+        assert.equal(plugin.status, "active");
+        await runPlugin(plugin, {}, failingHandler);
+        assert.equal(plugin.errorCount, 2);
+        assert.equal(plugin.status, "active");
+        await runPlugin(plugin, {}, failingHandler);
+        assert.equal(plugin.errorCount, 3);
+        assert.equal(plugin.status, "error");
+    });
+});

package/dist/kernel/pluginLoader.js

@@ -15,6 +15,20 @@ import { t } from "#i18n";
 import { pathToFileURL } from "url";
 import { PATHS } from "#config";
 import { buildSetupApi, cleanupPluginEvents } from "#manyapi";
+import { initCommandRegistry } from "#kernel/commandRegistry.js";
+/**
+ * Resolves the actual handler function out of either shape a plugin may
+ * export under `commands[fnName]`. Shared by the registry build step
+ * (commandRegistry.ts) and the dispatch step (runCommand.ts) so both
+ * agree on what counts as "this function is callable".
+ */
+export function resolvePluginCommandHandler(def) {
+    if (typeof def === "function")
+        return def;
+    if (def && typeof def === "object" && typeof def.handler === "function")
+        return def.handler;
+    return null;
+}
 const PLUGINS_DIR = path.join(PATHS.HOME, "plugins");
 export const pluginRegistry = new Map();
 let globalContract = null;
@@ -65,6 +79,7 @@ export async function loadPlugins(activePlugins) {
         await loadPlugin(name);
     }
     startConfigWatcher();
+    await initCommandRegistry();
     const total = pluginRegistry.size;
     const active = [...pluginRegistry.values()].filter(p => p.status === "active").length;
     const errors = total - active;
@@ -131,6 +146,7 @@ export async function loadPlugin(name, isReload = false) {
             status: "disabled",
             run: null,
             setup: null,
+            commands: null,
             exports: null,
             error: null,
             guardOptions: {},
@@ -146,6 +162,7 @@ export async function loadPlugin(name, isReload = false) {
             status: "disabled",
             run: null,
             setup: null,
+            commands: null,
             exports: null,
             error: null,
             guardOptions: {},
@@ -166,12 +183,20 @@ export async function loadPlugin(name, isReload = false) {
             status: "active",
             run: mod.default,
             setup: mod.setup ?? null,
+            commands: mod.commands ?? null,
             exports: mod.api ?? null,
             error: null,
             guardOptions: mod.guardOptions ?? {},
             errorCount: 0,
         });
-        logger.info(t(isReload ? "system.pluginReloaded" : "system.pluginLoaded", { name }));
+        // Phase 9: a plugin is a library of ready-to-use functions invoked as
+        // commands, not something that loads all its logic at boot — a line
+        // per plugin no longer earns its place in default startup output.
+        // Still available with --debug.
+        logger.debug(t(isReload ? "system.pluginReloaded" : "system.pluginLoaded", { name }));
+        if (isReload) {
+            await initCommandRegistry();
+        }
         watchPluginDirectory(name);
     }
     catch (e) {
@@ -183,11 +208,15 @@ export async function loadPlugin(name, isReload = false) {
             status: newErrorCount >= 3 ? "error" : "active",
             run: null,
             setup: null,
+            commands: null,
             exports: null,
             error: err,
             guardOptions: {},
             errorCount: newErrorCount,
         });
+        if (isReload) {
+            await initCommandRegistry();
+        }
     }
 }
 /**
@@ -266,6 +295,7 @@ export async function syncPlugins() {
             }
         }
     }
+    await initCommandRegistry();
 }
 /**
  * Watch a plugin's directory for changes.
@@ -328,6 +358,14 @@ function startConfigWatcher() {
         logger.warn(`[watcher] Failed to start config directory watcher: ${err.message}`);
     }
 }
+/**
+ * Tear down everything `loadPlugins()` started — config watcher, per-plugin
+ * directory watchers, and each plugin's exported `cleanup()` handler.
+ *
+ * Used by the process-shutdown path in main.ts and by tests that need a
+ * clean registry between cases. Idempotent: safe to call multiple times
+ * and safe to call before any plugin has been loaded.
+ */
 export async function cleanupPlugins() {
     if (configWatcher) {
         configWatcher.close();
@@ -352,3 +390,60 @@ export async function cleanupPlugins() {
         }
     }
 }
+export async function loadIntegrationPlugin() {
+    // Integration mode is opt-in: the bot never loads this plugin in
+    // production. The check has to happen before any filesystem work so
+    // a forgotten opt-in fails fast with a clear message, not a stack
+    // trace from a missing file or a permission error. We only enforce
+    // the explicit opt-in flag here — `TEST_CHAT` is consulted by the
+    // plugin itself at runtime, not by the loader.
+    if (process.env.MANYBOT_RUN_WHATSAPP_TESTS !== "1") {
+        throw new Error(`[pluginLoader] cannot load the integration plugin: ` +
+            `MANYBOT_RUN_WHATSAPP_TESTS=1 is required to opt in to the integration test harness.`);
+    }
+    const { INTEGRATION_PLUGIN_NAME, getIntegrationPluginDir } = await import("#kernel/integrationMode.js");
+    // Idempotent: if a previous load already registered the integration
+    // plugin, hand the same entry back rather than re-importing and
+    // duplicating the registry (and the in-process event listeners that
+    // would otherwise attach twice).
+    const existing = pluginRegistry.get(INTEGRATION_PLUGIN_NAME);
+    if (existing)
+        return existing;
+    const dir = getIntegrationPluginDir();
+    const pluginPath = `${dir}/index.ts`;
+    try {
+        const mod = await import(pathToFileURL(pluginPath).href);
+        if (typeof mod.default !== "function") {
+            throw new Error(`Integration plugin "${INTEGRATION_PLUGIN_NAME}" does not export a default function`);
+        }
+        const entry = {
+            name: INTEGRATION_PLUGIN_NAME,
+            status: "active",
+            run: mod.default,
+            setup: mod.setup ?? null,
+            commands: null,
+            exports: mod.api ?? null,
+            error: null,
+            guardOptions: {},
+            errorCount: 0,
+        };
+        pluginRegistry.set(INTEGRATION_PLUGIN_NAME, entry);
+        return entry;
+    }
+    catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        const entry = {
+            name: INTEGRATION_PLUGIN_NAME,
+            status: "error",
+            run: null,
+            setup: null,
+            commands: null,
+            exports: null,
+            error: err,
+            guardOptions: {},
+            errorCount: 1,
+        };
+        pluginRegistry.set(INTEGRATION_PLUGIN_NAME, entry);
+        throw err;
+    }
+}

package/dist/kernel/pluginLoader.test.js

@@ -0,0 +1,80 @@
+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-plugin-loader-"));
+process.env.MANYBOT_CONFIG_DIR = configDir;
+const { cleanupPlugins, loadPlugin, pluginRegistry, reloadPlugin } = await import("#kernel/pluginLoader.js");
+const pluginsDir = path.join(configDir, "plugins");
+async function writePlugin(name, manifest, source) {
+    const dir = path.join(pluginsDir, name);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, "manyplug.json"), manifest, "utf8");
+    if (source !== undefined)
+        await fs.writeFile(path.join(dir, "index.js"), source, "utf8");
+}
+beforeEach(async () => {
+    await cleanupPlugins();
+    pluginRegistry.clear();
+    await fs.rm(pluginsDir, { recursive: true, force: true });
+});
+after(async () => {
+    await cleanupPlugins();
+    await fs.rm(configDir, { recursive: true, force: true });
+});
+describe("kernel/pluginLoader", () => {
+    test("marks a plugin without a manifest as disabled", async () => {
+        await loadPlugin("missing");
+        assert.deepEqual(pluginRegistry.get("missing"), {
+            name: "missing",
+            status: "disabled",
+            run: null,
+            setup: null,
+            commands: null,
+            exports: null,
+            error: null,
+            guardOptions: {},
+            errorCount: 0,
+        });
+    });
+    test("loads an ESM plugin with optional public exports", async () => {
+        await writePlugin("hello", '{"main":"index.js"}', `
+      export default async function run() {}
+      export async function setup() {}
+      export const commands = { greet: { cmd: "greet", handler: async () => "hello" } }
+      export const api = { version: 1 }
+      export const guardOptions = { retries: 2 }
+    `);
+        await loadPlugin("hello");
+        const plugin = pluginRegistry.get("hello");
+        assert.ok(plugin);
+        assert.equal(plugin.status, "active");
+        assert.equal(typeof plugin.run, "function");
+        assert.equal(typeof plugin.setup, "function");
+        assert.equal(plugin.commands?.greet?.cmd, "greet");
+        assert.deepEqual(plugin.exports, { version: 1 });
+        assert.deepEqual(plugin.guardOptions, { retries: 2 });
+        assert.equal(plugin.errorCount, 0);
+    });
+    test("records a load error when a plugin has no default handler", async () => {
+        await writePlugin("invalid", "{}", "export const api = {};\n");
+        await loadPlugin("invalid");
+        const plugin = pluginRegistry.get("invalid");
+        assert.ok(plugin);
+        assert.equal(plugin.status, "error");
+        assert.equal(plugin.run, null);
+        assert.match(plugin.error?.message ?? "", /does not export a default function/);
+        assert.equal(plugin.errorCount, 3);
+    });
+    test("reloads an active plugin", async () => {
+        await writePlugin("reloadable", "{}", "export default async function run() {}\nexport const api = { version: 1 };\n");
+        await loadPlugin("reloadable");
+        assert.deepEqual(pluginRegistry.get("reloadable")?.exports, { version: 1 });
+        await reloadPlugin("reloadable");
+        const plugin = pluginRegistry.get("reloadable");
+        assert.equal(plugin?.status, "active");
+        assert.deepEqual(plugin?.exports, { version: 1 });
+        assert.equal(plugin?.errorCount, 0);
+    });
+});

package/dist/kernel/runCommand.js

@@ -0,0 +1,245 @@
+/**
+ * kernel/runCommand.ts
+ *
+ * ManyBot v6 — single kernel-side dispatcher for routed prefix
+ * commands. Centralising this gives Phase 8 a single try/catch hook
+ * (the "natural capture point" called out in MANYBOT-6.md) and keeps
+ * the per-command logic out of the message handler so each step
+ * (permission → required-arguments → sub-command routing → handler
+ * dispatch → crash alert) can be tested independently.
+ *
+ * Pipeline:
+ *   1. Resolve the parent entry by invocation (= cmd or alias).
+ *   2. Permission check (owner/scope/blacklist/whitelist/admin/botAdmin/cooldown).
+ *   3. Sub-command routing: if the parent has subcommands, look up the
+ *      next token; if a match exists, dispatch to the sub instead.
+ *   4. Required-argument validation against the matched entry's
+ *      declared `arguments:` block.
+ *   5. Handler dispatch via `runPlugin` (same timeout + 3-strikes guard
+ *      as the message handler uses for the legacy plugin.run path).
+ *   6. Crash capture: any throw inside step 5 fires `fireAlert` at
+ *      phase 8 hook level before re-raising; this is the unique
+ *      advantage of the unified dispatcher over the legacy
+ *      `for (plugin of pluginRegistry) await runPlugin(...)` loop.
+ */
+import { logger } from "#logger";
+import { t } from "#i18n";
+import { CMD_PREFIX } from "#config";
+import { fireAlert } from "./alerts.js";
+import { runPlugin } from "./pluginGuard.js";
+import { checkPermission } from "./commandPermissions.js";
+import { getCommandRegistry } from "./commandRegistry.js";
+import { pluginRegistry, resolvePluginCommandHandler } from "./pluginLoader.js";
+function flatten(target) {
+    if (target.kind === "sub") {
+        return {
+            kind: "sub",
+            entry: target.parent,
+            name: `${target.parent.cmd} ${target.sub.cmd}`,
+            permissions: target.sub.permissions,
+            arguments: target.sub.arguments ?? [],
+            args: target.args,
+        };
+    }
+    return {
+        kind: "parent",
+        entry: target.entry,
+        name: target.entry.cmd,
+        permissions: target.entry.permissions,
+        arguments: target.entry.arguments ?? [],
+        args: target.args,
+    };
+}
+/**
+ * Pure resolution — finds the parent + sub (if any) without invoking.
+ * `rawArgs` is the body fragment with the leading `<cmd> ` stripped.
+ */
+export function resolveDispatch(command, rawArgs) {
+    const registry = getCommandRegistry();
+    if (!registry)
+        return { target: { kind: "none" } };
+    const parentId = registry.byInvocation.get(command);
+    if (!parentId)
+        return { target: { kind: "none" } };
+    const entry = registry.byId.get(parentId);
+    if (!entry)
+        return { target: { kind: "none" } };
+    const trimmed = rawArgs.trim();
+    if (Object.keys(entry.subcommands).length === 0 || !trimmed) {
+        return { target: { kind: "parent", entry, args: trimmed ? trimmed.split(/\s+/) : [] } };
+    }
+    const token = trimmed.split(/\s+/)[0].toLowerCase();
+    const sub = entry.subcommands[token];
+    if (!sub) {
+        const remaining = trimmed.split(/\s+/).slice(1);
+        return {
+            target: { kind: "parent", entry, args: remaining },
+            unmatchedSubToken: token,
+        };
+    }
+    const rest = trimmed.split(/\s+/).slice(1);
+    return { target: { kind: "sub", parent: entry, sub, args: rest } };
+}
+/**
+ * Imperative run: takes the dispatcher-ready shapes (plugin, ctx,
+ * resolved target) and runs them through the unified pipeline.
+ *
+ * Returns a small result so the caller (the message handler) can
+ * decide whether to send any extra reply, log the action, or fall
+ * through to the legacy run loop.
+ */
+export async function runCommand(opts) {
+    const { resolution, pluginName, ctx, reply } = opts;
+    const { target } = resolution;
+    if (target.kind === "none") {
+        return { status: "no_dispatch", sentReply: null, suggestedReply: null };
+    }
+    const flat = flatten(target);
+    // Sub-tokens that don't match any declared sub go through the parent
+    // handler — same convention as a CLI tool with an unknown subcommand.
+    if (resolution.unmatchedSubToken && target.kind === "parent") {
+        const validSubs = Object.keys(target.entry.subcommands);
+        const help = t("commandRun.unknownSubcommand", {
+            sub: resolution.unmatchedSubToken,
+            cmd: target.entry.cmd,
+            valid: validSubs.join(", ") || "(none)",
+        });
+        await reply.text(help);
+        return { status: "unknown_sub", sentReply: help, suggestedReply: help };
+    }
+    // Permission check uses the resolved (parent OR sub) permissions.
+    const permEntry = target.kind === "sub" ? subAsEntry(target.parent, target.sub) : target.entry;
+    const perm = await checkPermission(permEntry, {
+        isGroup: ctx.chat.isGroup,
+        chatId: ctx.chat.id,
+        senderId: ctx.msg.sender,
+        isSenderAdmin: () => ctx.chat.isSenderAdmin(),
+        isBotAdmin: () => ctx.chat.isBotAdmin(),
+    });
+    if (!perm.allowed) {
+        if (perm.message) {
+            await reply.text(perm.message);
+        }
+        return { status: "permission_denied", sentReply: perm.message ?? null, suggestedReply: perm.message ?? null };
+    }
+    // Required-argument check — purely advisory, the plugin still gets
+    // called with whatever args arrived. Surface the kernel-side message
+    // + auto-generated usage before invoking.
+    const requiredCount = flat.arguments.filter(a => a.required).length;
+    if (requiredCount > flat.args.length) {
+        const usage = renderUsage(target);
+        const msg = `${t("commandRun.missingRequiredArg")}\n\n${usage}`;
+        await reply.text(msg);
+        return { status: "argument_missing", sentReply: msg, suggestedReply: msg };
+    }
+    // Wrap the dispatch in a try/catch and fire alerts on any throw.
+    // This is the Phase 8 hook.
+    try {
+        if (!pluginName) {
+            // text-only command handled below (caller will handle the fixed-text path).
+            return { status: "no_dispatch", sentReply: null, suggestedReply: null };
+        }
+        // The actual handler invocation is delegated to runPlugin (which
+        // enforces timeout + 3-strikes). Pass the resolved sub-function
+        // name via the unified entrypoint so handlers can be the same
+        // function whether called as the parent or as a sub.
+        const fnName = target.kind === "sub" ? target.sub.function : (target.entry.function ?? target.entry.cmd);
+        const plugin = lookupPlugin(pluginName);
+        const handler = plugin ? resolvePluginCommandHandler(plugin.commands?.[fnName]) : null;
+        if (!plugin || !handler) {
+            const msg = `Plugin "${pluginName}" does not expose handler for !${flat.name}`;
+            logger.warn(`[runCommand] ${msg}`);
+            return { status: "no_dispatch", sentReply: null, suggestedReply: msg };
+        }
+        await runPlugin(plugin, ctx, handler, { args: flat.args, subcommand: target.kind === "sub" ? target.sub.cmd : undefined }, { rethrow: true });
+        return { status: "executed", sentReply: null, suggestedReply: null };
+    }
+    catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        fireAlert("plugin_crash", {
+            plugin: pluginName,
+            command: flat.name,
+            kind: err.message?.startsWith("timed out") ? "timeout" : "exception",
+            message: err.message,
+        });
+        // Re-raise so pluginGuard can keep its 3-strike bookkeeping.
+        throw err;
+    }
+}
+/**
+ * Treat a sub-command as if it were a CommandEntry for permission
+ * checks. We materialise a virtual entry sharing the sub's resolved
+ * permissions, since `checkPermission` works against `CommandEntry`.
+ */
+function subAsEntry(parent, sub) {
+    return {
+        ...parent,
+        id: sub.id,
+        cmd: sub.cmd,
+        permissions: sub.permissions,
+        subcommands: {},
+        arguments: sub.arguments,
+        group: null,
+        manual: sub.manual,
+        categoryHiddenInScope: null,
+    };
+}
+/**
+ * Look up the real, live `PluginEntry` for a plugin command dispatch.
+ * `pluginRegistry` (from `pluginLoader.ts`) is the same module-level
+ * map `commandRegistry.ts` reads at build time — its `commands` field
+ * carries the plugin's raw `commands` export as-is (bare handler
+ * function or `{ handler, ... }` object); `resolvePluginCommandHandler`
+ * normalizes either shape into a callable handler.
+ *
+ * Returning the *real* entry (not a throwaway `{ name }` stand-in)
+ * matters: `runPlugin` (`pluginGuard.ts`) gates on `plugin.status ===
+ * "active"` and persists `errorCount`/3-strikes bookkeeping onto the
+ * object it's given — a fresh literal each call would silently no-op
+ * every dispatch (fails the `status` check) and never accumulate
+ * crash counts.
+ *
+ * NOTE: this is deliberately NOT `ctx.plugins.require(pluginName)` —
+ * that facet returns `PluginEntry.exports` (the plugin's pure `api`
+ * object, Phase 3's `export const api = {...}`, which never receives
+ * `ctx`). Command/sub-command handlers are a different facet
+ * (`PluginEntry.commands`) and always receive `ctx`.
+ */
+function lookupPlugin(pluginName) {
+    const plugin = pluginRegistry.get(pluginName);
+    if (!plugin || plugin.status !== "active" || !plugin.commands)
+        return null;
+    return plugin;
+}
+/**
+ * Render an auto-generated usage line for a command/sub. Format:
+ *   !<cmd>[ <sub>] [--<arg1> ...]
+ * Built from the declared `arguments:` block.
+ */
+export function renderUsage(target) {
+    if (target.kind === "none")
+        return "";
+    const flat = flatten(target);
+    const head = target.kind === "sub"
+        ? `${CMD_PREFIX}${target.parent.cmd} ${target.sub.cmd}`
+        : `${CMD_PREFIX}${flat.entry.cmd}`;
+    const headClean = head.replace(/\s+$/, "");
+    if (flat.arguments.length === 0)
+        return headClean;
+    const parts = [];
+    for (const arg of flat.arguments) {
+        const tok = arg.type === "boolean" ? `--${arg.name}[=true|false]` :
+            arg.type === "choice" ? `--${arg.name}=<${arg.choices?.join("|") ?? "..."}>` :
+                arg.type === "mention" ? `@<user>` :
+                    arg.type === "url" ? `<url>` :
+                        arg.type === "media_direct" ? `<media>` :
+                            arg.type === "media_reply" ? `<reply-media>` :
+                                arg.type === "number" ? `<n>` :
+                                    arg.type === "duration" ? `<duration>` :
+                                        arg.type === "quoted_text" ? `"<text>"` :
+                                            arg.type === "reply" ? `<reply>` :
+                                                `<${arg.name}>`;
+        parts.push(arg.required ? tok : `[${tok}]`);
+    }
+    return `${headClean} ${parts.join(" ")}`;
+}