manyplug 1.3.0

package/README.md

@@ -0,0 +1,34 @@
+![ManyPlug Banner](banner.png)
+
+CLI plugin manager for ManyBot.
+
+## Install
+
+```bash
+npm install -g @freakk.dev/manyplug
+# or
+npm link  # for development
+```
+
+## Usage
+
+```bash
+# Get help
+manyplug help [command]
+
+# Create new plugin
+manyplug init my-plugin --category games
+
+# Install from repository
+manyplug install many-ai
+
+# Install plugin from local path
+manyplug install --local ../my-plugin
+
+# List installed plugins
+manyplug list
+
+# Validate manyplug.json
+manyplug validate
+manyplug validate ./my-plugin
+```

package/bin/manyplug.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import { createRequire } from 'module';
+import { installCommand }          from '../src/install.js';
+import { listCommand }             from '../src/list.js';
+import { removeCommand }           from '../src/remove.js';
+import { enableCommand, disableCommand } from '../src/enable.js';
+import { syncCommand, updateCommand }    from '../src/sync.js';
+import { initCommand }             from '../src/init.js';
+import { validateCommand }         from '../src/validate.js';
+
+const pkg = createRequire(import.meta.url)('../package.json');
+
+// ------------------------------------------------------------
+// help
+// ------------------------------------------------------------
+
+function printHelp(cmd) {
+	if (!cmd) {
+		console.log(`manyplug ${pkg.version} — plugin manager for ManyBot`);
+		console.log('https://git.stxerr.dev/manyplug.git\n');
+		console.log('commands: init install remove list enable disable sync update validate');
+		console.log('options:  -v/--version  help <command>');
+		return;
+	}
+
+	const c = program.commands.find(c => c.name() === cmd || c.aliases().includes(cmd));
+	if (!c) { console.error(`unknown command: ${cmd}`); process.exit(1); }
+
+	const args = c.registeredArguments
+		.map(a => (a.required ? `<${a._name}>` : `[${a._name}]`)).join(' ');
+
+	console.log(`manyplug ${c.name()} ${args}`);
+	console.log(c.description());
+
+	if (c.aliases().length)
+		console.log(`aliases: ${c.aliases().join(', ')}`);
+
+	const opts = c.options;
+	if (opts.length) {
+		console.log('\noptions:');
+		for (const o of opts)
+			console.log(`  ${o.flags.padEnd(22)} ${o.description}`);
+	}
+}
+
+// ------------------------------------------------------------
+// program
+// ------------------------------------------------------------
+
+program
+	.name('manyplug')
+	.version(pkg.version, '-v, --version')
+	.helpOption(false);
+
+program.command('help [command]').description('show help for a command')
+	.action(cmd => { printHelp(cmd); process.exit(0); });
+
+program.command('init [name]').description('create new plugin boilerplate')
+	.option('-c, --category <cat>', 'category (games media utility service admin fun)', 'utility')
+	.option('--service', 'mark as background service plugin', false)
+	.action(initCommand);
+
+program.command('install [plugins...]').description('install plugins from registry or local path')
+	.option('-l, --local <path>', 'install from local path')
+	.option('-y, --yes',          'skip confirmation')
+	.option('--needed',           'skip already up-to-date plugins')
+	.action(installCommand);
+
+program.command('remove [plugins...]').alias('rm').description('remove installed plugins')
+	.option('-y, --yes',          'skip confirmation')
+	.option('--remove-deps',      'also uninstall npm dependencies')
+	.action(removeCommand);
+
+program.command('list').alias('ls').description('list installed plugins (enabled only by default)')
+	.option('-a, --all', 'include disabled plugins')
+	.action(listCommand);
+
+program.command('enable [plugins...]').description('enable plugins')
+	.action(enableCommand);
+
+program.command('disable [plugins...]').description('disable plugins')
+	.action(disableCommand);
+
+program.command('validate [path]').alias('val').description('validate manyplug.json')
+	.action(validateCommand);
+
+program.command('sync').description('sync local registry with remote')
+	.option('-f, --force', 'save even if nothing changed')
+	.action(syncCommand);
+
+program.command('update').description('install/update all plugins from remote')
+	.option('-y, --yes', 'skip confirmation')
+	.action(updateCommand);
+
+// ------------------------------------------------------------
+
+if (process.argv.length <= 2) { printHelp(); process.exit(0); }
+
+program.on('command:*', ([op]) => {
+	console.error(`unknown command: ${op}`);
+	console.error('run "manyplug help" for usage');
+	process.exit(1);
+});
+
+program.parse();

package/config.json

@@ -0,0 +1,14 @@
+{
+	"mirrors": [
+		{
+			"name": "Stxerr.dev",
+			"fetch": "https://git.stxerr.dev/manyplug-repo.git/plain",
+			"git": "https://git.stxerr.dev/manyplug-repo.git"
+		},
+		{
+			"name": "Codeberg",
+			"fetch": "https://codeberg.org/synt-xerror/manyplug-repo/raw/branch/master",
+			"git": "https://codeberg.org/synt-xerror/manyplug-repo"
+		}
+	]
+}	

package/docs/manyplug.1

@@ -0,0 +1,273 @@
+.TH MANYPLUG 1 "2026-04-20" "v0.1.0" "ManyPlug Manual"
+.SH NAME
+manyplug \- CLI plugin manager for ManyBot
+.SH SYNOPSIS
+.B manyplug
+.I command
+.RI [ options ]
+.RI [ arguments ]
+.SH DESCRIPTION
+.B manyplug
+is a command-line plugin manager designed specifically for ManyBot, a WhatsApp bot framework.
+It provides a complete plugin management system for creating, installing, enabling, disabling,
+removing, and validating plugins.
+.PP
+Plugins can be installed from remote registries (via git) or from local paths.
+Each plugin follows a standardized structure with metadata defined in
+.BR manyplug.json .
+.SH COMMANDS
+.SS "init [name]"
+Create a new plugin boilerplate with the proper directory structure.
+.PP
+Options:
+.RS
+.TP
+.BR \-c ", " \-\-category " <cat>"
+Plugin category: games, media, utility, service, admin, or fun (default: utility)
+.TP
+.B \-\-service
+Mark the plugin as a service plugin (runs in background)
+.RE
+.SS "install [plugins...]"
+Install one or more plugins from the registry or a local path.
+.PP
+Options:
+.RS
+.TP
+.BR \-l ", " \-\-local " <path>"
+Install from a local directory instead of the registry (single plugin only)
+.TP
+.BR \-y ", " \-\-yes
+Skip confirmation prompts
+.TP
+.B \-\-needed
+Skip reinstalling plugins that are already up-to-date (pacman-style)
+.RE
+.SS "remove [plugins...]"
+Remove installed plugins. Aliased as
+.BR rm .
+.PP
+Options:
+.RS
+.TP
+.BR \-y ", " \-\-yes
+Skip confirmation prompts
+.TP
+.B \-\-remove\-deps
+Also remove npm dependencies installed for the plugin
+.RE
+.SS "list"
+List all installed plugins (enabled only by default). Aliased as
+.BR ls .
+.PP
+Options:
+.RS
+.TP
+.BR \-a ", " \-\-all
+Include disabled plugins in the listing
+.RE
+.SS "enable [plugins...]"
+Enable one or more installed plugins. Enabled plugins are loaded by ManyBot on startup.
+.SS "disable [plugins...]"
+Disable one or more installed plugins. Disabled plugins remain installed but are not loaded.
+.SS "sync"
+Synchronize the local registry with remote repositories.
+.PP
+Options:
+.RS
+.TP
+.B \-\-no\-add
+Do not add new plugins discovered in the remote registry
+.TP
+.BR \-u ", " \-\-update
+Install or update plugins from the remote registry
+.RE
+.SS "update"
+Update all plugins from remote (equivalent to
+.BR "sync --update" ).
+.SS "validate [path]"
+Validate a plugin's
+.B manyplug.json
+configuration file. Aliased as
+.BR val .
+.PP
+If no path is specified, validates the current directory.
+.SH "PLUGIN STRUCTURE"
+A valid plugin follows this directory structure:
+.PP
+.RS
+.nf
+my-plugin/
+├── manyplug.json    # Plugin metadata (required)
+├── index.js         # Entry point (or as specified in main)
+├── locale/          # Translations (recommended)
+│   ├── pt.json
+│   ├── en.json
+│   └── es.json
+└── README.md        # Documentation
+.fi
+.RE
+.SH "MANYPLUG.JSON"
+The
+.B manyplug.json
+file defines plugin metadata. Required fields:
+.PP
+.RS
+.TP
+.B name
+Plugin name (lowercase letters, numbers, hyphens; 2-50 characters)
+.TP
+.B version
+Semantic version (e.g., "1.0.0")
+.TP
+.B category
+One of: games, media, utility, service, admin, fun
+.RE
+.PP
+Optional fields:
+.PP
+.RS
+.TP
+.B service
+Set to true for background service plugins
+.TP
+.B description
+Plugin description
+.TP
+.B author
+Author name
+.TP
+.B license
+License identifier (e.g., "MIT")
+.TP
+.B main
+Entry point file (default: "index.js")
+.TP
+.B dependencies
+npm dependencies object
+.TP
+.B externalDependencies
+System command dependencies object
+.RE
+.SH "SERVICE PLUGINS"
+Service plugins (marked with
+.B "service: true"
+) run continuously in the background rather than responding to commands.
+They are useful for tasks like tracking user activity, scheduled jobs, or maintaining state.
+.SH "EXTERNAL DEPENDENCIES"
+Plugins can declare system-level dependencies in
+.BR manyplug.json :
+.PP
+.RS
+.nf
+"externalDependencies": {
+  "ffmpeg": "ffmpeg",
+  "python3": {
+    "command": "python3",
+    "optional": true
+  }
+}
+.fi
+.RE
+.PP
+The
+.B validate
+command checks if these commands exist in the system PATH.
+.SH "REGISTRY"
+ManyPlug maintains a local
+.B registry.json
+file tracking installed plugins, their versions, categories, and whether they are local or remote.
+.PP
+The remote registry is fetched from configured mirrors (see
+.BR config.json ).
+.SH "PLUGIN ENTRY POINT"
+A plugin's entry file exports an async function receiving
+.B msg
+and
+.B api
+objects:
+.PP
+.RS
+.nf
+export default async function ({ msg, api }) {
+  if (!msg.is(CMD_PREFIX + "command")) return;
+  await msg.reply("Hello!");
+}
+.fi
+.RE
+.SH "FILES"
+.TP
+.I ./registry.json
+Local plugin registry tracking installed plugins
+.TP
+.I ./config.json
+ManyPlug configuration with mirror URLs
+.TP
+.I ./manyplug.json
+Plugin manifest (in plugin directories)
+.TP
+.I ./manybot.conf
+ManyBot plugin configuration (managed by enable/disable)
+.SH "EXAMPLES"
+Create a new utility plugin:
+.PP
+.RS
+.B manyplug init my-plugin --category utility
+.RE
+.PP
+Install plugins from the registry:
+.PP
+.RS
+.B manyplug install fun games
+.RE
+.PP
+Install from a local path:
+.PP
+.RS
+.B manyplug install --local ./my-custom-plugin
+.RE
+.PP
+Install without confirmation:
+.PP
+.RS
+.B manyplug install plugin-name --yes
+.RE
+.PP
+List all plugins including disabled:
+.PP
+.RS
+.B manyplug list --all
+.RE
+.PP
+Enable and disable plugins:
+.PP
+.RS
+.B manyplug enable plugin-a plugin-b
+.br
+.B manyplug disable plugin-a
+.RE
+.PP
+Sync with remote and update all plugins:
+.PP
+.RS
+.B manyplug sync --update
+.RE
+.PP
+Remove a plugin and its dependencies:
+.PP
+.RS
+.B manyplug remove plugin-name --remove-deps
+.RE
+.PP
+Validate a plugin configuration:
+.PP
+.RS
+.B manyplug validate ./my-plugin
+.RE
+.SH "SEE ALSO"
+.BR manybot (1)
+.SH "AUTHORS"
+Written by freakk.dev.
+.br
+Source available at: https://git.stxerr.dev/manyplug.git
+

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "manyplug",
+  "version": "1.3.0",
+  "description": "CLI plugin manager for ManyBot",
+  "man": ["docs/manyplug.1"],
+  "keywords": [
+    "manybot",
+    "plugin",
+    "cli",
+    "whatsapp"
+  ],
+  "license": "MIT",
+  "author": "freakkdev",
+  "type": "module",
+  "main": "./bin/manyplug.js",
+  "bin": {
+    "manyplug": "bin/manyplug.js"
+  },
+  "scripts": {
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@freakk.dev/manyplug": "^1.0.1",
+    "chalk": "^5.3.0",
+    "cli-progress": "^3.12.0",
+    "commander": "^11.0.0",
+    "fs": "^0.0.1-security",
+    "fs-extra": "^11.3.4",
+    "gradient-string": "^3.0.0",
+    "ora": "^8.0.1",
+    "pino": "^9.14.0",
+    "pino-pretty": "^11.0.0",
+    "sqlite3": "^5.1.7"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.4",
+    "vitest": "^4.1.4"
+  }
+}

package/src/enable.js

@@ -0,0 +1,86 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+const CONF_PATH   = path.join(process.cwd(), 'manybot.conf');
+const PLUGINS_DIR = path.join(process.cwd(), 'src', 'plugins');
+
+// ------------------------------------------------------------
+// conf file — PLUGINS=[a,b,c]
+// ------------------------------------------------------------
+
+async function readEnabled() {
+	if (!await fs.pathExists(CONF_PATH)) return [];
+	const raw = await fs.readFile(CONF_PATH, 'utf-8');
+	const match = raw.match(/PLUGINS=\[\s*([\s\S]*?)\s*\]/);
+	if (!match) return [];
+	return match[1].split(',').map(s => s.trim()).filter(Boolean);
+}
+
+async function writeEnabled(plugins) {
+	await fs.writeFile(CONF_PATH, `PLUGINS=[\n${plugins.map(p => p + ',').join('\n')}\n]\n`, 'utf-8');
+}
+
+// ------------------------------------------------------------
+// enable / disable commands
+// ------------------------------------------------------------
+
+async function toggle(names, action) {
+	if (!names.length) {
+		console.error(`usage: manyplug ${action} <plugin> [plugin2...]`);
+		process.exit(1);
+	}
+
+	const t       = Date.now();
+	const enabled = await readEnabled();
+	const set     = new Set(enabled);
+	const results = [];
+
+	for (const name of names) {
+		if (action === 'enable' && !await fs.pathExists(path.join(PLUGINS_DIR, name))) {
+			console.error(`x ${name}: not installed`);
+			results.push({ name, changed: false, notFound: true });
+			continue;
+		}
+		const was = set.has(name);
+		if (action === 'enable')  set.add(name);
+		else                      set.delete(name);
+		const changed = set.has(name) !== was;
+		results.push({ name, changed });
+	}
+
+	const changed = results.filter(r => r.changed);
+
+	if (changed.length) {
+		try {
+			await writeEnabled([...set]);
+		} catch (e) {
+			console.error(`error: ${e.message}`);
+			process.exit(1);
+		}
+	}
+
+	for (const r of results) {
+		if (r.notFound) continue; // already printed above
+		const symbol = action === 'enable' ? '+' : '-';
+		const note   = r.changed ? '' : ` (already ${action}d)`;
+		console.log(`${symbol} ${r.name}${note}`);
+	}
+
+	if (names.length > 1) {
+		const notFound = results.filter(r => r.notFound).length;
+		console.log(`${changed.length}/${names.length} changed  (${((Date.now() - t) / 1000).toFixed(2)}s)${notFound ? `  ${notFound} not found` : ''}`);
+	}
+
+	if (results.some(r => r.notFound)) process.exit(1);
+}
+
+export function enableCommand(input) {
+	const names = Array.isArray(input) ? input : (input ? [input] : []);
+	return toggle(names, 'enable');
+}
+
+export function disableCommand(input) {
+	const names = Array.isArray(input) ? input : (input ? [input] : []);
+	return toggle(names, 'disable');
+}
+

package/src/init.js

@@ -0,0 +1,111 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { formatSize } from './ui.js';
+
+const VALID_CATEGORIES = ['games', 'media', 'utility', 'service', 'admin', 'fun'];
+
+// ------------------------------------------------------------
+// templates
+// ------------------------------------------------------------
+
+const manyplugJson = (name, category, service) => ({
+	name, version: '1.0.0',
+	description: `${name} plugin for ManyBot`,
+	category, service,
+	author: '', license: 'MIT', main: 'index.js',
+	dependencies: {}, externalDependencies: {}
+});
+
+const indexJs = (name) => `\
+// ${name} — ManyBot plugin
+import { CMD_PREFIX } from "../../config.js";
+
+export default async function ({ msg, api }) {
+  if (!msg.is(CMD_PREFIX + "hi")) return;
+  await msg.reply("Hello!");
+}
+`;
+
+const localePt = (name) => ({ plugin: { name, description: `Plugin ${name} para ManyBot` }, commands: {} });
+const localeEn = (name) => ({ plugin: { name, description: `${name} plugin for ManyBot` },  commands: {} });
+
+const gitignore = () => `node_modules/\npackage-lock.json\n*.log\n.vscode/\n.DS_Store\ncoverage/\n`;
+
+const readme = (name) => `\
+# ${name}
+
+Plugin for ManyBot.
+
+## Installation
+
+\`\`\`bash
+manyplug install ${name}
+\`\`\`
+
+## Usage
+
+Describe how to use your plugin here.
+
+## License
+
+MIT
+`;
+
+// ------------------------------------------------------------
+// init command
+// ------------------------------------------------------------
+
+export async function initCommand(name, options = {}) {
+	const t = Date.now();
+
+	if (!name || !/^[a-z0-9-]+$/.test(name)) {
+		console.error('error: name must be lowercase letters, numbers, and hyphens only');
+		process.exit(1);
+	}
+
+	const category = VALID_CATEGORIES.includes(options.category) ? options.category : 'utility';
+	if (!VALID_CATEGORIES.includes(options.category)) {
+		console.warn(`warn: unknown category, using "utility"`);
+	}
+
+	const dir     = path.resolve(name);
+	const service = options.service || false;
+
+	if (await fs.pathExists(dir)) {
+		process.stdout.write(`"${name}" already exists, overwrite? [y/N] `);
+		const answer = await new Promise(res => process.stdin.once('data', d => res(d.toString().trim().toLowerCase())));
+		if (answer !== 'y') { console.log('cancelled'); process.exit(0); }
+	}
+
+	const f = (...p) => path.join(dir, ...p);
+
+	console.log(`creating ${name}  category=${category}  service=${service}`);
+
+	try {
+		await fs.ensureDir(f('locale'));
+		await fs.writeJson(f('manyplug.json'), manyplugJson(name, category, service), { spaces: 2 });
+		await fs.writeFile(f('index.js'), indexJs(name));
+		await fs.writeJson(f('locale', 'pt.json'), localePt(name), { spaces: 2 });
+		await fs.writeJson(f('locale', 'en.json'), localeEn(name), { spaces: 2 });
+		await fs.writeFile(f('.gitignore'), gitignore());
+		await fs.writeFile(f('README.md'), readme(name));
+	} catch (e) {
+		console.error(`error: ${e.message}`);
+		process.exit(1);
+	}
+
+	const size = await fs.stat(dir).then(() => getDirSize(dir));
+	console.log(`done  size=${formatSize(size)}  time=${((Date.now() - t) / 1000).toFixed(2)}s`);
+	console.log(`  cd ${name}`);
+	console.log(`  manyplug validate .`);
+	console.log(`  manyplug install --local .`);
+}
+
+async function getDirSize(dir) {
+	let total = 0;
+	for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
+		const p = path.join(dir, entry.name);
+		total += entry.isDirectory() ? await getDirSize(p) : (await fs.stat(p)).size;
+	}
+	return total;
+}