@theowlops/boombot 0.0.0-stage → 1.1.0

package/dist/node_modules/@boombot/plugins/manager.js

@@ -0,0 +1,243 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { mkdir, readFile, readdir } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+import { parseManifest, } from '@boombot/protocol';
+import { resolveWithin } from '@boombot/sandbox';
+const MANIFEST_FILE = 'boombot.plugin.json';
+const MAX_MANIFEST_BYTES = 64 * 1024;
+export class PluginManager {
+    tools;
+    deactivate;
+    manifests;
+    root;
+    configs;
+    logger;
+    constructor(tools, deactivate, manifests, root, configs, logger) {
+        this.tools = tools;
+        this.deactivate = deactivate;
+        this.manifests = manifests;
+        this.root = root;
+        this.configs = configs;
+        this.logger = logger;
+    }
+    static empty() {
+        return new PluginManager([], [], []);
+    }
+    static async load(root, configs = {}, log = () => { }) {
+        await mkdir(root, { recursive: true });
+        const tools = [];
+        const deactivate = [];
+        const manifests = [];
+        const ids = new Set();
+        const toolNames = new Set();
+        const entries = (await readdir(root, { withFileTypes: true }))
+            .filter((entry) => entry.isDirectory())
+            .sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+            const firstTool = tools.length;
+            let manifestId;
+            try {
+                const pluginRoot = await resolveWithin(root, entry.name);
+                const manifestPath = await resolveWithin(pluginRoot, MANIFEST_FILE);
+                const rawText = await readFile(manifestPath, 'utf8');
+                if (Buffer.byteLength(rawText) > MAX_MANIFEST_BYTES) {
+                    throw new Error(`manifest exceeds ${String(MAX_MANIFEST_BYTES)} bytes`);
+                }
+                const parsed = parseManifest(JSON.parse(rawText));
+                if (!parsed.ok)
+                    throw new Error(parsed.errors.join('; '));
+                const manifest = parsed.manifest;
+                manifestId = manifest.id;
+                if (ids.has(manifest.id))
+                    throw new Error(`duplicate plugin id '${manifest.id}'`);
+                ids.add(manifest.id);
+                const config = configs[manifest.id] ?? {};
+                const configErrors = validateConfig(config, manifest.configSchema);
+                if (configErrors.length > 0)
+                    throw new Error(`invalid config: ${configErrors.join('; ')}`);
+                const modulePath = await resolveWithin(pluginRoot, manifest.entry ?? 'index.js');
+                const moduleUrl = pathToFileURL(modulePath).href;
+                const imported = await import(__rewriteRelativeImportExtension(/* @vite-ignore */ moduleUrl));
+                const plugin = resolvePlugin(imported);
+                let accepting = true;
+                const api = {
+                    config,
+                    registerTool: (definition, handler) => {
+                        if (!accepting)
+                            throw new Error('tools must be registered during plugin activation');
+                        if (!manifest.capabilities.includes('tool.register')) {
+                            throw new Error(`plugin '${manifest.id}' did not declare capability 'tool.register'`);
+                        }
+                        validateToolDefinition(definition);
+                        const name = pluginToolName(manifest.id, definition.name);
+                        if (toolNames.has(name))
+                            throw new Error(`duplicate plugin tool '${name}'`);
+                        toolNames.add(name);
+                        tools.push({
+                            localName: definition.name,
+                            handler,
+                            definition: {
+                                name,
+                                description: `[Plugin ${manifest.id}] ${definition.description}`,
+                                parameters: definition.parameters,
+                            },
+                        });
+                    },
+                    log: (level, message) => log(level, message, { plugin: manifest.id }),
+                };
+                await plugin.activate(api);
+                accepting = false;
+                if (typeof plugin.deactivate === 'function')
+                    deactivate.push(() => plugin.deactivate?.());
+                manifests.push(manifest);
+                log('info', 'plugin loaded', { plugin: manifest.id, version: manifest.version });
+            }
+            catch (error) {
+                for (const removed of tools.splice(firstTool))
+                    toolNames.delete(removed.definition.name);
+                if (manifestId !== undefined)
+                    ids.delete(manifestId);
+                log('warn', 'plugin failed to load', {
+                    directory: entry.name,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        return new PluginManager(tools, deactivate, manifests, root, configs, log);
+    }
+    get toolNames() {
+        return this.tools.map((tool) => tool.definition.name);
+    }
+    /** Hot-reload plugins in-memory without restarting the gateway or dropping sessions. */
+    async reload() {
+        if (!this.root)
+            return this.toolNames;
+        for (const stop of [...this.deactivate].reverse()) {
+            try {
+                await stop();
+            }
+            catch {
+                // cleanup never throws
+            }
+        }
+        this.tools = [];
+        this.deactivate = [];
+        this.manifests.length = 0;
+        const fresh = await PluginManager.load(this.root, this.configs, this.logger);
+        this.tools.push(...fresh.tools);
+        this.deactivate.push(...fresh.deactivate);
+        this.manifests.push(...fresh.manifests);
+        return this.toolNames;
+    }
+    registerTools(registry) {
+        for (const tool of this.tools) {
+            registry.registerTool(tool.definition, async (call, signal) => {
+                try {
+                    signal?.throwIfAborted();
+                    const result = await tool.handler({
+                        id: call.id,
+                        name: tool.localName,
+                        arguments: call.arguments,
+                    }, signal);
+                    signal?.throwIfAborted();
+                    if (typeof result?.output !== 'string')
+                        return failure(call, 'plugin returned no string output');
+                    return { callId: call.id, name: call.name, output: result.output, error: result.error === true };
+                }
+                catch (error) {
+                    if (signal?.aborted === true)
+                        throw error;
+                    return failure(call, error instanceof Error ? error.message : 'plugin tool failed');
+                }
+            });
+        }
+    }
+    async close() {
+        for (const stop of [...this.deactivate].reverse())
+            await stop();
+    }
+}
+function resolvePlugin(module) {
+    const candidate = module.default ?? module.plugin ?? module;
+    if (typeof candidate !== 'object' || candidate === null ||
+        typeof candidate.activate !== 'function') {
+        throw new Error('entry module must export a plugin object with activate(api)');
+    }
+    return candidate;
+}
+function validateToolDefinition(definition) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/.test(definition.name)) {
+        throw new Error(`invalid plugin tool name '${definition.name}'`);
+    }
+    if (typeof definition.description !== 'string' || definition.description.trim() === '') {
+        throw new Error(`plugin tool '${definition.name}' needs a description`);
+    }
+    if (typeof definition.parameters !== 'object' || definition.parameters === null || Array.isArray(definition.parameters)) {
+        throw new Error(`plugin tool '${definition.name}' parameters must be a JSON Schema object`);
+    }
+}
+function pluginToolName(pluginId, localName) {
+    const safeId = pluginId.replace(/[^A-Za-z0-9_-]/g, '_');
+    const safeName = localName.replace(/[^A-Za-z0-9_-]/g, '_');
+    return `plugin_${safeId}_${safeName}`.slice(0, 64);
+}
+function failure(call, message) {
+    return { callId: call.id, name: call.name, output: message, error: true };
+}
+function validateConfig(value, schema, path = 'config') {
+    const errors = [];
+    if (schema.enum !== undefined && !schema.enum.some((item) => Object.is(item, value))) {
+        errors.push(`${path} is not an allowed value`);
+        return errors;
+    }
+    if (schema.type === 'object') {
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            return [`${path} must be an object`];
+        }
+        const record = value;
+        for (const required of schema.required ?? []) {
+            if (!(required in record))
+                errors.push(`${path}.${required} is required`);
+        }
+        for (const [key, child] of Object.entries(schema.properties ?? {})) {
+            if (key in record)
+                errors.push(...validateConfig(record[key], child, `${path}.${key}`));
+        }
+        if (schema.additionalProperties === false) {
+            for (const key of Object.keys(record)) {
+                if (schema.properties?.[key] === undefined)
+                    errors.push(`${path}.${key} is not allowed`);
+            }
+        }
+    }
+    else if (schema.type === 'array') {
+        if (!Array.isArray(value))
+            return [`${path} must be an array`];
+        if (schema.items !== undefined) {
+            value.forEach((item, index) => errors.push(...validateConfig(item, schema.items, `${path}[${String(index)}]`)));
+        }
+    }
+    else if (schema.type === 'string' && typeof value !== 'string') {
+        errors.push(`${path} must be a string`);
+    }
+    else if (schema.type === 'number' && (typeof value !== 'number' || !Number.isFinite(value))) {
+        errors.push(`${path} must be a finite number`);
+    }
+    else if (schema.type === 'integer' && (typeof value !== 'number' || !Number.isInteger(value))) {
+        errors.push(`${path} must be an integer`);
+    }
+    else if (schema.type === 'boolean' && typeof value !== 'boolean') {
+        errors.push(`${path} must be a boolean`);
+    }
+    else if (schema.type === 'null' && value !== null) {
+        errors.push(`${path} must be null`);
+    }
+    return errors;
+}

package/dist/node_modules/@boombot/plugins/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@boombot/plugins",
+  "version": "2.0.0",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  }
+}

package/dist/node_modules/@boombot/protocol/gateway-protocol/commands-channels.d.ts

@@ -0,0 +1,125 @@
+import { z } from "zod";
+/**
+ * Command defs pending merge into the protocol barrel.
+ * Shape mirrors `COMMAND_SCHEMAS`: `{ [type]: { type, payload, response } }`.
+ */
+export declare const EXTRA_COMMAND_DEFS: {
+    readonly "channel.connect": {
+        type: string;
+        payload: z.ZodUnion<[z.ZodObject<{
+            channel: z.ZodLiteral<"telegram">;
+            botToken: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            channel: "telegram";
+            botToken: string;
+        }, {
+            channel: "telegram";
+            botToken: string;
+        }>, z.ZodObject<{
+            channel: z.ZodLiteral<"zalo">;
+            mode: z.ZodOptional<z.ZodLiteral<"oa">>;
+            appId: z.ZodOptional<z.ZodString>;
+            appSecret: z.ZodOptional<z.ZodString>;
+            redirectUri: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            channel: "zalo";
+            redirectUri: string;
+            mode?: "oa" | undefined;
+            appId?: string | undefined;
+            appSecret?: string | undefined;
+        }, {
+            channel: "zalo";
+            redirectUri: string;
+            mode?: "oa" | undefined;
+            appId?: string | undefined;
+            appSecret?: string | undefined;
+        }>, z.ZodObject<{
+            channel: z.ZodLiteral<"zalo">;
+            mode: z.ZodLiteral<"personal">;
+        }, "strip", z.ZodTypeAny, {
+            mode: "personal";
+            channel: "zalo";
+        }, {
+            mode: "personal";
+            channel: "zalo";
+        }>]>;
+        response: z.ZodDiscriminatedUnion<"status", [z.ZodObject<{
+            status: z.ZodLiteral<"connected">;
+            displayName: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            status: "connected";
+            displayName: string;
+        }, {
+            status: "connected";
+            displayName: string;
+        }>, z.ZodObject<{
+            status: z.ZodLiteral<"authorization_required">;
+            authorizationUrl: z.ZodString;
+            expiresAt: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            status: "authorization_required";
+            authorizationUrl: string;
+            expiresAt: string;
+        }, {
+            status: "authorization_required";
+            authorizationUrl: string;
+            expiresAt: string;
+        }>, z.ZodObject<{
+            status: z.ZodLiteral<"qr_required">;
+            qrDataUrl: z.ZodString;
+            expiresAt: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            status: "qr_required";
+            expiresAt: string;
+            qrDataUrl: string;
+        }, {
+            status: "qr_required";
+            expiresAt: string;
+            qrDataUrl: string;
+        }>]>;
+    };
+    readonly "channel.pair": {
+        type: string;
+        payload: z.ZodObject<{
+            channel: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            channel: string;
+        }, {
+            channel: string;
+        }>;
+        response: z.ZodObject<{
+            /** `BOOM-######` pairing code the user types on the channel. */
+            code: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            code: string;
+        }, {
+            code: string;
+        }>;
+    };
+    readonly "channel.unpair": {
+        type: string;
+        payload: z.ZodObject<{
+            channel: z.ZodString;
+            target: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            channel: string;
+            target: string;
+        }, {
+            channel: string;
+            target: string;
+        }>;
+        response: z.ZodObject<{
+            ok: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            ok: boolean;
+        }, {
+            ok: boolean;
+        }>;
+    };
+};
+/** Union of the extra command type literals. */
+export type ExtraCommandType = keyof typeof EXTRA_COMMAND_DEFS;
+/** Validated payload type for an extra command. */
+export type ExtraCommandPayload<T extends ExtraCommandType> = z.infer<(typeof EXTRA_COMMAND_DEFS)[T]["payload"]>;
+/** Validated response type for an extra command. */
+export type ExtraCommandResponse<T extends ExtraCommandType> = z.infer<(typeof EXTRA_COMMAND_DEFS)[T]["response"]>;

package/dist/node_modules/@boombot/protocol/gateway-protocol/commands-channels.js

@@ -0,0 +1,76 @@
+import { z } from "zod";
+/**
+ * Extra channel command definitions, additive-only.
+ *
+ * `channel.connect` / `channel.pair` / `channel.unpair` are handled by
+ * `channels/src/handlers.ts` (which re-validates the payload
+ * with the same rules so the handler does not depend on this barrel).
+ * They are wired into `COMMAND_SCHEMAS` in `commands.ts` (additive merge)
+ * and re-exported from the protocol barrel as `CHANNEL_EXTRA_COMMAND_DEFS`
+ * for handlers that need the def directly.
+ */
+const channelPair = {
+    type: "channel.pair",
+    payload: z.object({
+        channel: z.string().min(1),
+    }),
+    response: z.object({
+        /** `BOOM-######` pairing code the user types on the channel. */
+        code: z.string().min(1),
+    }),
+};
+const channelUnpair = {
+    type: "channel.unpair",
+    payload: z.object({
+        channel: z.string().min(1),
+        target: z.string().min(1),
+    }),
+    response: z.object({
+        ok: z.boolean(),
+    }),
+};
+const channelConnect = {
+    type: "channel.connect",
+    payload: z.union([
+        z.object({
+            channel: z.literal("telegram"),
+            botToken: z.string().min(1),
+        }),
+        z.object({
+            channel: z.literal("zalo"),
+            mode: z.literal("oa").optional(),
+            appId: z.string().min(1).optional(),
+            appSecret: z.string().min(1).optional(),
+            redirectUri: z.string().url(),
+        }),
+        z.object({
+            channel: z.literal("zalo"),
+            mode: z.literal("personal"),
+        }),
+    ]),
+    response: z.discriminatedUnion("status", [
+        z.object({
+            status: z.literal("connected"),
+            displayName: z.string().min(1),
+        }),
+        z.object({
+            status: z.literal("authorization_required"),
+            authorizationUrl: z.string().url(),
+            expiresAt: z.string().datetime(),
+        }),
+        z.object({
+            status: z.literal("qr_required"),
+            qrDataUrl: z.string().startsWith("data:image/png;base64,"),
+            expiresAt: z.string().datetime(),
+        }),
+    ]),
+};
+/**
+ * Command defs pending merge into the protocol barrel.
+ * Shape mirrors `COMMAND_SCHEMAS`: `{ [type]: { type, payload, response } }`.
+ */
+export const EXTRA_COMMAND_DEFS = {
+    "channel.connect": channelConnect,
+    "channel.pair": channelPair,
+    "channel.unpair": channelUnpair,
+};

package/dist/node_modules/@boombot/protocol/gateway-protocol/commands-plugins.d.ts

@@ -0,0 +1,220 @@
+import { z } from 'zod';
+export declare const pluginInfoSchema: z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    capabilities: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    directory: z.ZodOptional<z.ZodString>;
+    entry: z.ZodOptional<z.ZodString>;
+    isValid: z.ZodBoolean;
+    error: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    version: string;
+    capabilities: string[];
+    isValid: boolean;
+    error?: string | undefined;
+    directory?: string | undefined;
+    displayName?: string | undefined;
+    description?: string | undefined;
+    entry?: string | undefined;
+}, {
+    id: string;
+    version: string;
+    isValid: boolean;
+    error?: string | undefined;
+    directory?: string | undefined;
+    displayName?: string | undefined;
+    description?: string | undefined;
+    capabilities?: string[] | undefined;
+    entry?: string | undefined;
+}>;
+export declare const marketplacePluginSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodString;
+    author: z.ZodString;
+    capabilities: z.ZodArray<z.ZodString, "many">;
+    tags: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    id: string;
+    version: string;
+    description: string;
+    capabilities: string[];
+    author: string;
+    tags: string[];
+}, {
+    name: string;
+    id: string;
+    version: string;
+    description: string;
+    capabilities: string[];
+    author: string;
+    tags: string[];
+}>;
+export declare const PLUGIN_COMMAND_DEFS: {
+    readonly 'plugin.list': {
+        readonly type: "plugin.list";
+        readonly payload: z.ZodDefault<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>>;
+        readonly response: z.ZodObject<{
+            plugins: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                version: z.ZodString;
+                displayName: z.ZodOptional<z.ZodString>;
+                description: z.ZodOptional<z.ZodString>;
+                capabilities: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+                directory: z.ZodOptional<z.ZodString>;
+                entry: z.ZodOptional<z.ZodString>;
+                isValid: z.ZodBoolean;
+                error: z.ZodOptional<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                id: string;
+                version: string;
+                capabilities: string[];
+                isValid: boolean;
+                error?: string | undefined;
+                directory?: string | undefined;
+                displayName?: string | undefined;
+                description?: string | undefined;
+                entry?: string | undefined;
+            }, {
+                id: string;
+                version: string;
+                isValid: boolean;
+                error?: string | undefined;
+                directory?: string | undefined;
+                displayName?: string | undefined;
+                description?: string | undefined;
+                capabilities?: string[] | undefined;
+                entry?: string | undefined;
+            }>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            plugins: {
+                id: string;
+                version: string;
+                capabilities: string[];
+                isValid: boolean;
+                error?: string | undefined;
+                directory?: string | undefined;
+                displayName?: string | undefined;
+                description?: string | undefined;
+                entry?: string | undefined;
+            }[];
+        }, {
+            plugins: {
+                id: string;
+                version: string;
+                isValid: boolean;
+                error?: string | undefined;
+                directory?: string | undefined;
+                displayName?: string | undefined;
+                description?: string | undefined;
+                capabilities?: string[] | undefined;
+                entry?: string | undefined;
+            }[];
+        }>;
+    };
+    readonly 'plugin.marketplace': {
+        readonly type: "plugin.marketplace";
+        readonly payload: z.ZodDefault<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>>;
+        readonly response: z.ZodObject<{
+            marketplace: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                name: z.ZodString;
+                version: z.ZodString;
+                description: z.ZodString;
+                author: z.ZodString;
+                capabilities: z.ZodArray<z.ZodString, "many">;
+                tags: z.ZodArray<z.ZodString, "many">;
+            }, "strip", z.ZodTypeAny, {
+                name: string;
+                id: string;
+                version: string;
+                description: string;
+                capabilities: string[];
+                author: string;
+                tags: string[];
+            }, {
+                name: string;
+                id: string;
+                version: string;
+                description: string;
+                capabilities: string[];
+                author: string;
+                tags: string[];
+            }>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            marketplace: {
+                name: string;
+                id: string;
+                version: string;
+                description: string;
+                capabilities: string[];
+                author: string;
+                tags: string[];
+            }[];
+        }, {
+            marketplace: {
+                name: string;
+                id: string;
+                version: string;
+                description: string;
+                capabilities: string[];
+                author: string;
+                tags: string[];
+            }[];
+        }>;
+    };
+    readonly 'plugin.install': {
+        readonly type: "plugin.install";
+        readonly payload: z.ZodObject<{
+            spec: z.ZodString;
+            force: z.ZodOptional<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            spec: string;
+            force?: boolean | undefined;
+        }, {
+            spec: string;
+            force?: boolean | undefined;
+        }>;
+        readonly response: z.ZodObject<{
+            ok: z.ZodBoolean;
+            id: z.ZodString;
+            message: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            message: string;
+            ok: boolean;
+        }, {
+            id: string;
+            message: string;
+            ok: boolean;
+        }>;
+    };
+    readonly 'plugin.uninstall': {
+        readonly type: "plugin.uninstall";
+        readonly payload: z.ZodObject<{
+            id: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+        }, {
+            id: string;
+        }>;
+        readonly response: z.ZodObject<{
+            ok: z.ZodBoolean;
+            id: z.ZodString;
+            message: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            message: string;
+            ok: boolean;
+        }, {
+            id: string;
+            message: string;
+            ok: boolean;
+        }>;
+    };
+};