Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

15.8 KB
Raw Blame
/**
 * `mercury plugins …` from a shell. Same commands and wording as `/plugins`
 * in chat (it runs the same handler), forwarded to the background Mercury
 * when one is running, so that process starts and stops the plugins itself.
 * `validate` is the author-side conformance kit and runs here.
 */
import type { Command } from 'commander';
import chalk from 'chalk';
import { resolve } from 'node:path';
import type { ChannelMessage } from '../types/channel.js';

async function run(line: string): Promise<void> {
  const { handlePluginsCommand } = await import('../plugins/commands.js');
  const msg: ChannelMessage = {
    id: `cli-plugins-${Date.now()}`,
    channelId: 'cli',
    channelType: 'cli',
    senderId: 'owner',
    content: line,
    timestamp: Date.now(),
  };
  let failed = false;
  await handlePluginsCommand(line, msg, {
    // 'cli-batch': a one-shot shell command; guided setup runs interactively below instead.
    type: 'cli-batch',
    send: async (text) => {
      if (text.startsWith('✗')) failed = true;
      // Chat wording says "/plugins x"; in a shell it's "mercury plugins x".
      console.log(text.replace(/(^|[\s:(])\/plugins\b/g, '$1mercury plugins'));
    },
  });
  if (failed) process.exitCode = 1;
}

function quote(args: string[]): string {
  return args.map((a) => (/\s/.test(a) ? `"${a}"` : a)).join(' ');
}

export function registerPluginsCli(program: Command): void {
  const plugins = program
    .command('plugins')
    .alias('plugin')
    .description('Install, enable, disable, update and remove plugins');

  plugins.command('list', { isDefault: true }).alias('ls').description('Installed and available plugins').action(() => run('/plugins list'));
  plugins.command('search <text...>').description('Find plugins in the catalog').action((text: string[]) => run(`/plugins search ${quote(text)}`));
  plugins.command('info <id>').description('Details, tools and permissions').action((id: string) => run(`/plugins info ${id}`));
  plugins
    .command('install <source>')
    .alias('add')
    .description('Install from the catalog (id), a folder, a .tgz, an https URL or github:owner/repo')
    .option('-y, --yes', 'Skip the confirmation')
    .option('--no-setup', 'Don\'t walk through the plugin\'s setup afterwards')
    .action(async (source: string, opts: { yes?: boolean; setup?: boolean }) => {
      const before = process.exitCode;
      await run(`/plugins install ${source}${opts.yes ? ' --yes' : ''}`);
      if (!opts.yes || process.exitCode !== before || opts.setup === false || !process.stdin.isTTY) return;
      const id = await installedIdFor(source);
      if (id) await interactive('setup', id);
    });

  plugins
    .command('setup <id>')
    .description('Walk through a plugin\'s setup (settings, and linking for channels like WhatsApp)')
    .action((id: string) => interactive('setup', id));

  plugins
    .command('open <id>')
    .alias('menu')
    .description('A plugin\'s menu: settings, link, turn off, uninstall')
    .action((id: string) => interactive('menu', id));
  plugins.command('enable <id>').description('Turn a plugin on').action((id: string) => run(`/plugins enable ${id}`));
  plugins.command('disable <id>').description('Turn a plugin off (keeps its data and settings)').action((id: string) => run(`/plugins disable ${id}`));
  plugins.command('update [id]').description('Update one plugin, or all from the catalog').action((id?: string) => run(`/plugins update ${id ?? 'all'}`));
  plugins.command('rollback <id>').description('Go back to the previous installed version').action((id: string) => run(`/plugins rollback ${id}`));
  plugins
    .command('uninstall <id>')
    .alias('remove')
    .description('Remove a plugin (keeps its data unless --purge)')
    .option('--purge', 'Also delete its data and settings')
    .option('-y, --yes', 'Skip the confirmation')
    .action((id: string, opts: { purge?: boolean; yes?: boolean }) => run(`/plugins uninstall ${id}${opts.purge ? ' --purge' : ''}${opts.yes ? ' --yes' : ''}`));
  plugins.command('set <id> <key> <value...>').description('Change a plugin setting').action((id: string, key: string, value: string[]) => run(`/plugins set ${id} ${key} ${value.join(' ')}`));

  plugins
    .command('pair <id>')
    .description('Link the account for a channel plugin (e.g. WhatsApp): scan a QR code, or use --code')
    .option('--code <phone>', 'Get an 8-character pairing code for this phone number instead of a QR code')
    .action(async (id: string, opts: { code?: string }) => {
      await pairChannel(id, opts.code);
      setTimeout(() => process.exit(process.exitCode ?? 0), 50).unref();
    });

  plugins
    .command('test <id>')
    .description('Send the owner a test message through a channel plugin (e.g. WhatsApp)')
    .action(async (id: string) => {
      const { getPluginService } = await import('../plugins/service.js');
      try {
        console.log(chalk.green(`  ✓ ${await getPluginService().testChannel(id)}`));
      } catch (err) {
        console.error(chalk.red(`  ✗ ${(err as Error).message}`));
        process.exitCode = 1;
      }
    });

  plugins
    .command('unlink <id>')
    .description('Log a channel plugin out of its account (you can pair again later)')
    .action(async (id: string) => {
      const { getPluginService } = await import('../plugins/service.js');
      try {
        await getPluginService().unlink(id);
        console.log(chalk.green(`  ✓ ${id} unlinked.`));
      } catch (err) {
        console.error(chalk.red(`  ✗ ${(err as Error).message}`));
        process.exitCode = 1;
      }
    });

  plugins
    .command('init <id>')
    .description('Start a new plugin in ./<id> (for plugin authors)')
    .option('--out-of-process', 'An MCP server in its own process instead of a module inside Mercury')
    .action(async (id: string, opts: { outOfProcess?: boolean }) => {
      const { scaffoldPlugin } = await import('../plugins/scaffold.js');
      try {
        const dir = scaffoldPlugin(process.cwd(), id, opts.outOfProcess ? 'out-of-process' : 'in-process');
        console.log('');
        console.log(chalk.green(`  ✓ Created ${dir}`));
        console.log(chalk.dim(`    cd ${id} && mercury plugins validate . && mercury plugins install . --yes`));
        console.log('');
      } catch (err) {
        console.error(chalk.red(`  ✗ ${(err as Error).message}`));
        process.exitCode = 1;
      }
    });

  plugins
    .command('pack [folder]')
    .description('Package a plugin as .tgz and print its checksum and catalog entry (for plugin authors)')
    .option('-o, --out <dir>', 'Where to write the .tgz', '.')
    .action(async (folder: string | undefined, opts: { out: string }) => {
      const { packPlugin } = await import('../plugins/scaffold.js');
      try {
        const r = await packPlugin(resolve(folder ?? '.'), resolve(opts.out));
        console.log('');
        console.log(chalk.green(`  ✓ ${r.file}`));
        console.log(chalk.dim(`    ${(r.size / 1024).toFixed(1)} KB · sha256 ${r.sha256}`));
        console.log('');
        console.log('  Catalog entry (fix the artifact URL once the release exists):');
        console.log(JSON.stringify(r.entry, null, 2).replace(/^/gm, '  '));
        console.log('');
      } catch (err) {
        console.error(chalk.red(`  ✗ ${(err as Error).message}`));
        process.exitCode = 1;
      }
    });

  plugins
    .command('validate [folder]')
    .description('Check a plugin package the way Mercury will run it (for plugin authors)')
    .option('--json', 'Print the report as JSON')
    .action(async (folder: string | undefined, opts: { json?: boolean }) => {
      const { runConformance } = await import('../plugins/conformance.js');
      const report = await runConformance(resolve(folder ?? '.'));
      if (opts.json) {
        console.log(JSON.stringify(report, null, 2));
      } else {
        console.log('');
        console.log(chalk.bold(`  ${report.id ? `${report.id}@${report.version}` : 'plugin'} conformance`));
        for (const c of report.checks) {
          console.log(`  ${c.ok ? chalk.green('✓') : chalk.red('✗')} ${c.name}${c.detail ? chalk.dim(` · ${c.detail}`) : ''}`);
        }
        console.log('');
        console.log(report.ok ? chalk.green('  Ready to install and publish.') : chalk.red('  Fix the ✗ items above before publishing.'));
        console.log('');
      }
      if (!report.ok) process.exitCode = 1;
      // An out-of-process server or a plugin timer must not hold the CLI open.
      setTimeout(() => process.exit(process.exitCode ?? 0), 50).unref();
    });
}

/** `mercury doctor --plugins`: what's installed, what's off and why, and what to do. */
export async function runPluginDoctor(): Promise<void> {
  const { getPluginService } = await import('../plugins/service.js');
  const { isSafeModeRequested } = await import('../plugins/manager.js');
  const { readState } = await import('../plugins/store.js');
  const svc = getPluginService();
  console.log('');
  console.log(chalk.bold('  Plugins'));
  console.log(chalk.dim(`  ${svc.mode === 'daemon' ? 'Asking the running Mercury' : svc.mode === 'offline' ? 'Mercury is not running: showing what is on disk' : 'This process runs plugins'}`));
  let problems = 0;
  try {
    const { items, safeMode, catalogError } = await svc.list();
    if (safeMode || isSafeModeRequested()) console.log(chalk.yellow('  ⚠ Safe mode is on: no plugin runs until Mercury restarts without --safe-mode / MERCURY_PLUGINS=off.'));
    const boot = readState().boot;
    if (boot.failedBoots > 0) console.log(chalk.yellow(`  ⚠ Mercury failed to start ${boot.failedBoots} time(s) right after a plugin change${boot.lastChange ? ` (${boot.lastChange.id})` : ''}.`));
    const installed = items.filter((i) => i.installedVersion);
    if (!installed.length) console.log(chalk.dim('  No plugins installed.'));
    for (const i of installed) {
      const bad = i.status === 'error' || i.status === 'incompatible' || (i.disabled && i.disabled.code !== 'user');
      if (bad) problems++;
      const mark = i.status === 'enabled' ? chalk.green('✓') : bad ? chalk.red('✗') : chalk.dim('○');
      const why = i.status === 'incompatible' ? i.incompatibleReason : i.status === 'error' ? i.lastError ?? 'enabled but not running' : i.disabled && i.disabled.code !== 'user' ? `turned off automatically (${i.disabled.code}): ${i.disabled.message}` : i.status;
      console.log(`  ${mark} ${i.id}@${i.installedVersion} ${chalk.dim(`· ${why}`)}`);
      if (bad && i.disabled && ['errors', 'crashed', 'activation', 'boot-guard'].includes(i.disabled.code)) {
        console.log(chalk.dim(`      fix: mercury plugins update ${i.id}, or mercury plugins rollback ${i.id}, then mercury plugins enable ${i.id}`));
      } else if (bad && i.disabled?.code === 'integrity') {
        console.log(chalk.dim(`      fix: its files changed since install. Reinstall it: mercury plugins install ${i.id} --yes`));
      }
    }
    if (catalogError) console.log(chalk.dim(`  Catalog: ${catalogError}`));
  } catch (err) {
    problems++;
    console.log(chalk.red(`  ✗ ${(err as Error).message}`));
  }
  console.log('');
  if (problems) process.exitCode = 1;
}

async function pairChannel(id: string, phone?: string): Promise<void> {
  const { getPluginService } = await import('../plugins/service.js');
  const svc = getPluginService();
  if (svc.mode === 'offline') {
    console.error(chalk.red('  ✗ Mercury is not running. Start it (mercury start), then run this again.'));
    process.exitCode = 1;
    return;
  }
  const qrcode = (await import('qrcode-terminal')).default;
  const show = (st: { qr?: string; pairCode?: string }) => {
    if (st.pairCode) {
      console.log('');
      console.log(`  Pairing code: ${chalk.bold.cyan(st.pairCode)}`);
      console.log(chalk.dim('  On the phone with the spare number: WhatsApp → Settings → Linked devices → Link a device → Link with phone number instead, then type the code.'));
    } else if (st.qr) {
      console.log('');
      qrcode.generate(st.qr, { small: true }, (q: string) => console.log(q.replace(/^/gm, '  ')));
      console.log(chalk.dim('  On the phone with the spare number: WhatsApp → Settings → Linked devices → Link a device, then scan. The code refreshes every ~20 seconds.'));
    }
  };
  console.log('');
  console.log(chalk.yellow('  ⚠ This uses an unofficial WhatsApp protocol. Link a spare number you can afford to lose, not your main one.'));
  try {
    let st = await svc.pair(id, phone ? { method: 'code', phone } : { method: 'qr' });
    if (st.state === 'connected') {
      console.log(chalk.green(`  ✓ Already linked${st.account ? ` as ${st.account}` : ''}.`));
      return;
    }
    show(st);
    let lastShown = st.qr ?? st.pairCode;
    const deadline = Date.now() + 3 * 60_000;
    while (Date.now() < deadline) {
      await new Promise((r) => setTimeout(r, 2000));
      const next = await svc.channelStatus(id);
      if (!next) continue;
      st = next;
      if (st.state === 'connected') {
        console.log('');
        console.log(chalk.green(`  ✓ Linked${st.account ? ` as ${st.account}` : ''}. Message this number from your owner number to talk to Mercury.`));
        return;
      }
      if (st.state === 'error' || st.state === 'logged-out') {
        console.error(chalk.red(`  ✗ ${st.detail ?? st.state}`));
        process.exitCode = 1;
        return;
      }
      const current = st.qr ?? st.pairCode;
      if (current && current !== lastShown && !phone) {
        lastShown = current;
        show(st);
      }
    }
    console.error(chalk.red('  ✗ Timed out waiting for the link. Run the command again.'));
    process.exitCode = 1;
  } catch (err) {
    console.error(chalk.red(`  ✗ ${(err as Error).message}`));
    process.exitCode = 1;
  }
}

/** The plugin id a just-installed source refers to (catalog id, or read from the package). */
async function installedIdFor(source: string): Promise<string | null> {
  const { getPluginService } = await import('../plugins/service.js');
  const { items } = await getPluginService().list();
  const installed = items.filter((i) => i.installedVersion);
  const direct = installed.find((i) => i.id === source);
  if (direct) return direct.id;
  // A path or URL: the most recently installed one is the best guess; ask the state file.
  const { readState } = await import('../plugins/store.js');
  const state = readState();
  const latest = Object.entries(state.plugins).sort((a, b) => Date.parse(b[1].updatedAt) - Date.parse(a[1].updatedAt))[0];
  return latest?.[0] ?? null;
}

/** Run a guided dialog in the terminal. */
async function interactive(kind: 'setup' | 'menu', id: string): Promise<void> {
  const { getPluginService } = await import('../plugins/service.js');
  const { PluginDialog, renderPrompt } = await import('../plugins/dialog.js');
  const svc = getPluginService();
  const dialog = kind === 'setup' ? await PluginDialog.setup(svc, id) : await PluginDialog.menu(svc, id, true);
  if (!dialog) {
    console.log(kind === 'setup' ? `  ${id} has nothing to set up (or isn't installed).` : `  No plugin called "${id}".`);
    return;
  }
  if (!process.stdin.isTTY) {
    console.log('  This needs an interactive terminal. In chat, use /plugins ' + (kind === 'setup' ? `setup ${id}` : id) + '.');
    process.exitCode = 1;
    return;
  }
  const { createInterface } = await import('node:readline/promises');
  const rl = createInterface({ input: process.stdin, output: process.stdout });
  const clean = (t: string) => t.replace(/\*([^*\n]+)\*/g, (_m, x) => chalk.bold(x));
  try {
    for (;;) {
      const prompt = await dialog.current();
      if (!prompt) break;
      console.log('');
      console.log(clean(renderPrompt(prompt, false)).replace(/^/gm, '  '));
      const answer = await rl.question(chalk.cyan('  › '));
      const r = await dialog.answer(answer);
      if (r.message) console.log(clean(r.message).replace(/^/gm, '  '));
      if (r.finished) break;
    }
  } finally {
    rl.close();
  }
  console.log('');
  setTimeout(() => process.exit(process.exitCode ?? 0), 50).unref();
}