@manybot/manybot 5.7.0 → 5.9.0

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

@@ -6,7 +6,7 @@
  *   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
+ *   5. Watching plugin files, config files and commands.yaml for hot reloading
  */
 import fs from "fs";
 import path from "path";
@@ -15,10 +15,41 @@ 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;
 let globalStore = null;
+/**
+ * Live WaContract + BotStore the kernel most-recently wired through
+ * `setupPlugins()`. Exposed for the integration-test harness only
+ * (see `src/plugins/__manybot_integration__/` and the
+ * `*.integration.test.ts` suite under the project root): production
+ * code paths go through `ctx.wa.contract` / `ctx.store`, not through
+ * this module-scoped singleton.
+ *
+ * Returns `null` when the bot hasn't connected yet (or after a
+ * disconnect). The integration suite waits for a non-null value
+ * before issuing any real round-trip.
+ */
+export function getGlobalKernelRefs() {
+    if (!globalContract || !globalStore)
+        return null;
+    return { contract: globalContract, store: globalStore };
+}
 const pluginWatchers = new Map();
 // fs.watch's `recursive: true` emulates recursion on Linux by opening one
 // inotify watch per subdirectory — a plugin shipping its own node_modules
@@ -65,6 +96,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 +163,7 @@ export async function loadPlugin(name, isReload = false) {
             status: "disabled",
             run: null,
             setup: null,
+            commands: null,
             exports: null,
             error: null,
             guardOptions: {},
@@ -146,6 +179,7 @@ export async function loadPlugin(name, isReload = false) {
             status: "disabled",
             run: null,
             setup: null,
+            commands: null,
             exports: null,
             error: null,
             guardOptions: {},
@@ -166,12 +200,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 +225,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 +312,7 @@ export async function syncPlugins() {
             }
         }
     }
+    await initCommandRegistry();
 }
 /**
  * Watch a plugin's directory for changes.
@@ -305,22 +352,68 @@ export function unwatchPlugin(name) {
     }
 }
 /**
- * Watch the config directory for manyplug.toml or manybot.toml changes.
+ * Reload the command registry from disk (commands.yaml + imports).
+ *
+ * Mirrors `reloadPlugin()`: callable on its own and safe to invoke from
+ * a watcher. Unlike `reloadPlugin()` there's no setup retry / disable
+ * state to track — `initCommandRegistry()` either builds a fresh
+ * `CommandRegistry` from the current file content or leaves the
+ * previous one in place via `commandsConfig.ts`'s own error handling
+ * (a malformed YAML logs an error and returns null; `initCommandRegistry`
+ * then falls back to the empty defaults).
+ */
+export async function reloadCommandRegistry() {
+    try {
+        await initCommandRegistry();
+        logger.info(`[watcher] Command registry reloaded from commands.yaml.`);
+    }
+    catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        logger.error(`[watcher] Failed to reload command registry: ${err.message}`);
+    }
+}
+/**
+ * Watch the config directory for changes to manyplug.toml / manybot.toml
+ * (plugin list sync) or to commands.yaml and its .yaml/.yml imports
+ * (command registry reload). Both paths share the same 500ms debounce
+ * so a save that emits several inotify events only fires once.
  */
 function startConfigWatcher() {
     if (configWatcher)
         return;
+    const isTomlChange = (filename) => filename === "manyplug.toml" || filename === "manybot.toml";
+    const isYamlChange = (filename) => {
+        if (!filename)
+            return false;
+        const lower = filename.toLowerCase();
+        return lower.endsWith(".yaml") || lower.endsWith(".yml");
+    };
     try {
         let configTimeout = null;
+        let yamlTimeout = null;
+        const scheduleTomlReload = (filename) => {
+            if (!isTomlChange(filename))
+                return;
+            if (configTimeout)
+                clearTimeout(configTimeout);
+            configTimeout = setTimeout(async () => {
+                logger.info(`[watcher] Config file change detected: ${filename}. Syncing plugins...`);
+                await syncPlugins();
+            }, 500);
+        };
+        const scheduleYamlReload = (filename) => {
+            if (!isYamlChange(filename))
+                return;
+            if (yamlTimeout)
+                clearTimeout(yamlTimeout);
+            yamlTimeout = setTimeout(async () => {
+                logger.info(`[watcher] commands.yaml change detected (${filename}). Reloading command registry...`);
+                await reloadCommandRegistry();
+            }, 500);
+        };
         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);
-            }
+            scheduleTomlReload(filename);
+            scheduleYamlReload(filename);
         });
     }
     catch (e) {
@@ -328,6 +421,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 +453,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,190 @@
+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, loadPlugins, pluginRegistry, reloadCommandRegistry, reloadPlugin } = await import("#kernel/pluginLoader.js");
+const { getCommandRegistry } = await import("#kernel/commandRegistry.js");
+const pluginsDir = path.join(configDir, "plugins");
+const commandsFile = path.join(configDir, "commands.yaml");
+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");
+}
+async function waitFor(label, read, timeoutMs = 3000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const value = read();
+        if (value !== undefined)
+            return value;
+        await new Promise((r) => setTimeout(r, 50));
+    }
+    throw new Error(`timed out waiting for ${label}`);
+}
+beforeEach(async () => {
+    await cleanupPlugins();
+    pluginRegistry.clear();
+    await fs.rm(pluginsDir, { recursive: true, force: true });
+    await fs.rm(commandsFile, { force: true });
+    await fs.rm(path.join(configDir, "menu.yaml"), { 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);
+    });
+});
+describe("kernel/pluginLoader — commands.yaml hot reload", () => {
+    test("reloadCommandRegistry re-reads commands.yaml and rebuilds the registry", async () => {
+        await writePlugin("reloaddummy", '{"main":"index.js"}', `
+      export default async function run() {}
+    `);
+        await loadPlugins(["reloaddummy"]);
+        await fs.writeFile(commandsFile, `
+defaults:
+  notifyChanges: false
+helloReload:
+  cmd: hello
+  plugin: reloaddummy
+  desc: "First version"
+  functions: []
+`, "utf8");
+        await reloadCommandRegistry();
+        const registry = getCommandRegistry();
+        assert.ok(registry, "registry should be initialized after reload");
+        assert.equal(registry.byInvocation.get("hello"), "helloReload");
+        assert.equal(registry.byId.get("helloReload")?.desc, "First version");
+        assert.equal(registry.defaults.notifyChanges, false);
+        await fs.writeFile(commandsFile, `
+helloReload:
+  cmd: hello
+  plugin: reloaddummy
+  desc: "Second version"
+  functions: []
+`, "utf8");
+        await reloadCommandRegistry();
+        const registry2 = getCommandRegistry();
+        assert.ok(registry2);
+        assert.equal(registry2.byId.get("helloReload")?.desc, "Second version");
+        assert.equal(registry2.defaults.notifyChanges, true, "defaults should reset to built-in when omitted");
+    });
+    test("config watcher reloads the registry when commands.yaml is edited", async () => {
+        await writePlugin("watchdummy", '{"main":"index.js"}', `
+      export default async function run() {}
+    `);
+        await loadPlugins(["watchdummy"]);
+        assert.equal(getCommandRegistry()?.byInvocation.get("watch"), undefined);
+        await fs.writeFile(commandsFile, `
+helloWatch:
+  cmd: watch
+  plugin: watchdummy
+  desc: "Watcher picks this up"
+  functions: []
+`, "utf8");
+        const registry = await waitFor("registry to pick up commands.yaml change", () => {
+            const r = getCommandRegistry();
+            return r?.byId.get("helloWatch")?.desc === "Watcher picks this up" ? r : undefined;
+        });
+        assert.equal(registry.byInvocation.get("watch"), "helloWatch");
+    });
+    test("config watcher reloads the registry when an imported YAML file is edited", async () => {
+        await writePlugin("importdummy", '{"main":"index.js"}', `
+      export default async function run() {}
+    `);
+        await fs.writeFile(path.join(configDir, "menu.yaml"), `
+helloImport:
+  cmd: importcmd
+  plugin: importdummy
+  desc: "From menu.yaml (first)"
+  functions: []
+`, "utf8");
+        await fs.writeFile(commandsFile, `import: menu.yaml\n`, "utf8");
+        await loadPlugins(["importdummy"]);
+        const first = await waitFor("initial import to be picked up", () => {
+            const r = getCommandRegistry();
+            return r?.byId.get("helloImport")?.desc === "From menu.yaml (first)" ? r : undefined;
+        });
+        assert.equal(first.byInvocation.get("importcmd"), "helloImport");
+        await fs.writeFile(path.join(configDir, "menu.yaml"), `
+helloImport:
+  cmd: importcmd
+  plugin: importdummy
+  desc: "From menu.yaml (second)"
+  functions: []
+`, "utf8");
+        const second = await waitFor("imported yaml change to be picked up", () => {
+            const r = getCommandRegistry();
+            return r?.byId.get("helloImport")?.desc === "From menu.yaml (second)" ? r : undefined;
+        });
+        assert.equal(second.byInvocation.get("importcmd"), "helloImport");
+    });
+    test("config watcher ignores non-yaml/non-toml files in PATHS.HOME", async () => {
+        await writePlugin("ignoredummy", '{"main":"index.js"}', `
+      export default async function run() {}
+    `);
+        await loadPlugins(["ignoredummy"]);
+        const registryBefore = getCommandRegistry();
+        await fs.writeFile(path.join(configDir, "README.md"), "unrelated", "utf8");
+        await new Promise((r) => setTimeout(r, 800));
+        const registryAfter = getCommandRegistry();
+        assert.equal(registryAfter, registryBefore, "registry reference must be stable when no relevant file changed");
+    });
+});