@theowlops/boombot 0.0.0-stage → 1.1.1

package/dist/cli/cli/registry.js

@@ -0,0 +1,185 @@
+/**
+ * Command registry — every `boombot` command as a spec + handler.
+ *
+ * To add a command: append a spec here and a handler below. Help text,
+ * typo suggestions, flag validation and vocabulary checks all derive
+ * from this list — nothing is declared anywhere else.
+ */
+import { runDoctor, printDoctorReport } from "../commands/doctor.js";
+import { runGateway } from "../commands/gateway.js";
+import { isSupportedMigrateSource, printMigrateReport, runMigrateFromOpenClaw, } from "../commands/migrate.js";
+import { runSetup } from "../commands/setup.js";
+import { runPluginList, runPluginInstall, runPluginUninstall } from "../commands/plugin.js";
+import { CliError } from "./cli-error.js";
+async function setupHandler(_ctx) {
+    await runSetup();
+}
+async function doctorHandler(ctx) {
+    const report = await runDoctor();
+    if (ctx.json) {
+        console.log(JSON.stringify({ ok: report.ok, checks: report.checks }, null, 2));
+        return report.ok ? 0 : 1;
+    }
+    return printDoctorReport(report);
+}
+async function migrateHandler(ctx) {
+    const raw = ctx.flags['from'];
+    const from = typeof raw === 'string' ? raw : 'openclaw';
+    if (!isSupportedMigrateSource(from)) {
+        throw new CliError({
+            code: 'INVALID_FLAG_VALUE',
+            message: `unsupported migrate source: ${from} (expected "openclaw" or a path)`,
+            nextSteps: ['Run `boombot migrate --help` for usage.'],
+        });
+    }
+    const report = await runMigrateFromOpenClaw({
+        from: from === 'openclaw' ? undefined : from,
+    });
+    if (ctx.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        printMigrateReport(report);
+    }
+    return 0;
+}
+async function gatewayHandler(ctx) {
+    const noBrowser = ctx.flags['no-browser'] === true || process.env['BOOMBOT_NO_BROWSER'] === '1';
+    await runGateway({ noBrowser });
+}
+async function pluginListHandler(ctx) {
+    const marketplace = ctx.flags['marketplace'] === true;
+    await runPluginList({ marketplace });
+    return 0;
+}
+async function pluginInstallHandler(ctx) {
+    const spec = ctx.positionals[0] ?? '';
+    const force = ctx.flags['force'] === true;
+    return await runPluginInstall(spec, force);
+}
+async function pluginUninstallHandler(ctx) {
+    const pluginId = ctx.positionals[0] ?? '';
+    return await runPluginUninstall(pluginId);
+}
+export const REGISTRY = [
+    {
+        spec: {
+            path: ['setup'],
+            aliases: [['init']],
+            summary: 'Interactive first-run wizard (config, API key, provider)',
+            usage: 'boombot setup',
+            flags: [],
+            examples: ['boombot setup'],
+            notes: ['Prints the API key exactly once — store it somewhere safe.'],
+        },
+        handler: setupHandler,
+    },
+    {
+        spec: {
+            path: ['doctor'],
+            aliases: [['dr']],
+            summary: 'Check environment health (config, permissions, gateway, provider)',
+            usage: 'boombot doctor [--json]',
+            flags: [],
+            examples: ['boombot doctor', 'boombot doctor --json'],
+            notes: ['Exit code 0 when every check passes, 1 otherwise.'],
+        },
+        handler: doctorHandler,
+    },
+    {
+        spec: {
+            path: ['migrate'],
+            aliases: [['import']],
+            summary: 'Import an OpenClaw config (best effort, never overwrites)',
+            usage: 'boombot migrate [--from openclaw|<path>]',
+            flags: [
+                {
+                    name: 'from',
+                    description: 'Migration source: "openclaw" or an explicit config path',
+                    takesValue: true,
+                    valueName: '<source>',
+                },
+            ],
+            examples: ['boombot migrate', 'boombot migrate --from ~/old-openclaw.json'],
+            notes: ['Never overwrites existing BoomBot files.'],
+        },
+        handler: migrateHandler,
+    },
+    {
+        spec: {
+            path: ['gateway'],
+            aliases: [['serve']],
+            summary: 'Start the gateway and web UI (automatic setup on first launch)',
+            usage: 'boombot gateway [--no-browser]',
+            flags: [
+                {
+                    name: 'no-browser',
+                    description: "Don't auto-open the browser",
+                    takesValue: false,
+                    env: 'BOOMBOT_NO_BROWSER',
+                },
+            ],
+            examples: ['boombot', 'boombot gateway', 'boombot gateway --no-browser'],
+            notes: ['No command defaults to gateway. Existing configuration and keys are preserved.'],
+        },
+        handler: gatewayHandler,
+    },
+    {
+        spec: {
+            path: ['plugin', 'list'],
+            aliases: [['plugins'], ['plugin', 'ls']],
+            summary: 'List installed plugins or browse the marketplace',
+            usage: 'boombot plugin list [--marketplace]',
+            flags: [
+                {
+                    name: 'marketplace',
+                    description: 'Show available plugins in the marketplace',
+                    takesValue: false,
+                    short: 'm',
+                },
+            ],
+            examples: ['boombot plugin list', 'boombot plugin list --marketplace'],
+            notes: ['Lists extensions installed in ~/.boombot/plugins.'],
+        },
+        handler: pluginListHandler,
+    },
+    {
+        spec: {
+            path: ['plugin', 'install'],
+            aliases: [['plugin', 'add'], ['plugin', 'i']],
+            summary: 'Install a plugin from marketplace, local dir, git or npm',
+            usage: 'boombot plugin install <name|path|url> [--force]',
+            acceptsPositionals: true,
+            flags: [
+                {
+                    name: 'force',
+                    description: 'Reinstall or overwrite existing plugin',
+                    takesValue: false,
+                    short: 'f',
+                },
+            ],
+            examples: [
+                'boombot plugin install browser',
+                'boombot plugin install github',
+                'boombot plugin install ./my-local-plugin',
+                'boombot plugin install https://github.com/org/boombot-plugin-custom',
+            ],
+            notes: ['Installs plugin into ~/.boombot/plugins/<id>.'],
+        },
+        handler: pluginInstallHandler,
+    },
+    {
+        spec: {
+            path: ['plugin', 'uninstall'],
+            aliases: [['plugin', 'remove'], ['plugin', 'rm']],
+            summary: 'Uninstall a plugin by ID',
+            usage: 'boombot plugin uninstall <plugin-id>',
+            acceptsPositionals: true,
+            flags: [],
+            examples: ['boombot plugin uninstall boombot.browser'],
+            notes: ['Irreversible: deletes the plugin folder from ~/.boombot/plugins/<id>. Run with care. Requires gateway restart.'],
+            destructive: true,
+        },
+        handler: pluginUninstallHandler,
+    },
+];

package/dist/cli/cli/spec.js

@@ -0,0 +1,41 @@
+/**
+ * `CommandSpec` — declarative command definitions (orca-inspired).
+ *
+ * Every CLI command is data: path, aliases, summary, usage, flags, examples.
+ * All help text is GENERATED from the registry — never hand-written in two
+ * places. Typo suggestions, flag validation and vocabulary checks all read
+ * the same specs, so they cannot drift from what the CLI actually accepts.
+ */
+/** All accepted spellings of a spec: canonical path first, then aliases. */
+export function specPaths(spec) {
+    return spec.aliases !== undefined ? [spec.path, ...spec.aliases] : [spec.path];
+}
+/**
+ * Flags accepted on EVERY command. Shown in a separate help section so
+ * per-command flag lists stay honest about what the command itself takes.
+ */
+export const GLOBAL_FLAGS = [
+    {
+        name: 'json',
+        description: 'Output machine-readable JSON (for scripting)',
+        takesValue: false,
+    },
+    {
+        name: 'config',
+        description: 'Override the config path',
+        takesValue: true,
+        valueName: '<path>',
+        env: 'BOOMBOT_CONFIG',
+    },
+    {
+        name: 'profile',
+        description: 'Use an isolated bot profile',
+        takesValue: true,
+        valueName: '<name>',
+        env: 'BOOMBOT_PROFILE',
+    },
+    { name: 'help', short: 'h', description: 'Show help for a command', takesValue: false },
+    { name: 'version', short: 'v', description: 'Show version', takesValue: false },
+];
+/** Short single-dash forms, derived from GLOBAL_FLAGS so they cannot drift. */
+export const SHORT_FLAGS = Object.fromEntries(GLOBAL_FLAGS.filter((f) => f.short !== undefined).map((f) => [f.short, f.name]));

package/dist/cli/cli/suggest.js

@@ -0,0 +1,125 @@
+/**
+ * "Did you mean?" — typo recovery over the live command registry.
+ *
+ * Adapted from orca's `command-suggestion.ts`: suggestions are ranked from
+ * the REGISTERED specs (never a hand-maintained list), so they cannot drift
+ * from what the CLI accepts. Self-contained levenshtein (~20 lines, no dep).
+ */
+import { specPaths } from "./spec.js";
+/** Max edit distance for a normal suggestion. */
+export const SUGGESTION_THRESHOLD = 3;
+/** Max suggestions returned per lookup. */
+export const MAX_SUGGESTIONS = 3;
+/**
+ * A typo near a destructive verb (`remov` → `remove`) still signals that
+ * intent, but an unrelated verb must never recover into it. Kept at 1.
+ */
+export const DESTRUCTIVE_INTENT_THRESHOLD = 1;
+export function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    let prev = new Array(n + 1);
+    let curr = new Array(n + 1);
+    for (let j = 0; j <= n; j++)
+        prev[j] = j;
+    for (let i = 1; i <= m; i++) {
+        curr[0] = i;
+        const ca = a.charCodeAt(i - 1);
+        for (let j = 1; j <= n; j++) {
+            const cost = ca === b.charCodeAt(j - 1) ? 0 : 1;
+            const deletion = (prev[j] ?? 0) + 1;
+            const insertion = (curr[j - 1] ?? 0) + 1;
+            const substitution = (prev[j - 1] ?? 0) + cost;
+            curr[j] = Math.min(deletion, insertion, substitution);
+        }
+        const tmp = prev;
+        prev = curr;
+        curr = tmp;
+    }
+    return prev[n] ?? 0;
+}
+function finalToken(path) {
+    return path[path.length - 1] ?? '';
+}
+/**
+ * Destructiveness is declared on the spec (single source of truth); the
+ * intent verbs are the final tokens of every destructive path/alias so the
+ * guard tracks the registry instead of a hand-maintained list.
+ */
+function destructiveVerbs(specs) {
+    const verbs = new Set();
+    for (const spec of specs) {
+        if (spec.destructive === true) {
+            for (const p of specPaths(spec))
+                verbs.add(finalToken(p));
+        }
+    }
+    return verbs;
+}
+/**
+ * Only unlock destructive candidates when the input token is itself a
+ * near-miss of a destructive verb — a benign typo must never recover into
+ * an irreversible action.
+ */
+function intendsDestruction(inputToken, verbs) {
+    for (const verb of verbs) {
+        if (Math.abs(inputToken.length - verb.length) <= DESTRUCTIVE_INTENT_THRESHOLD &&
+            levenshtein(inputToken, verb) <= DESTRUCTIVE_INTENT_THRESHOLD) {
+            return true;
+        }
+    }
+    return false;
+}
+function rankByDistance(scored) {
+    return scored
+        .filter((e) => e.distance > 0 && e.distance <= SUGGESTION_THRESHOLD)
+        .sort((a, b) => a.distance - b.distance || a.label.localeCompare(b.label))
+        .slice(0, MAX_SUGGESTIONS)
+        .map((e) => e.label);
+}
+/**
+ * Suggest registered commands for mistyped input. Matches at the same depth
+ * so a one-token typo never suggests a nested group or vice versa.
+ */
+export function suggestCommands(specs, inputTokens) {
+    const input = inputTokens.join(' ');
+    const allowDestructive = intendsDestruction(finalToken(inputTokens), destructiveVerbs(specs));
+    const seen = new Set();
+    const scored = [];
+    for (const spec of specs) {
+        if (spec.hidden === true)
+            continue;
+        if (spec.destructive === true && !allowDestructive)
+            continue;
+        for (const candidate of specPaths(spec)) {
+            // Same-depth matching: a 1-token typo only sees 1-token commands.
+            const shown = inputTokens.length === 1 ? candidate.slice(0, 1) : candidate;
+            if (shown.length !== inputTokens.length)
+                continue;
+            const joined = shown.join(' ');
+            if (seen.has(joined))
+                continue;
+            seen.add(joined);
+            if (Math.abs(input.length - joined.length) <= SUGGESTION_THRESHOLD) {
+                scored.push({ label: joined, distance: levenshtein(input, joined) });
+            }
+        }
+    }
+    return rankByDistance(scored);
+}
+/** Suggest flag names for a mistyped `--flag`. */
+export function suggestFlags(flag, validFlags) {
+    const scored = [];
+    for (const candidate of validFlags) {
+        if (Math.abs(flag.length - candidate.length) <= SUGGESTION_THRESHOLD) {
+            scored.push({ label: candidate, distance: levenshtein(flag, candidate) });
+        }
+    }
+    return rankByDistance(scored);
+}

package/dist/cli/cli/version.js

@@ -0,0 +1,30 @@
+/**
+ * CLI version — read from the nearest package.json, never hardcoded.
+ *
+ * Works in both layouts by checking the two known package roots:
+ * - monorepo dev:  `apps/cli/src/cli/version.ts` → `apps/cli/package.json`
+ * - npm dist:      `dist/cli/cli/version.js`      → `package.json` (package root)
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+export function resolveCliVersion() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    for (const pkgPath of [
+        path.resolve(here, '..', '..', 'package.json'),
+        path.resolve(here, '..', '..', '..', 'package.json'),
+    ]) {
+        try {
+            const parsed = JSON.parse(readFileSync(pkgPath, 'utf8'));
+            const version = typeof parsed === 'object' && parsed !== null
+                ? parsed.version
+                : undefined;
+            if (typeof version === 'string' && version !== '')
+                return version;
+        }
+        catch {
+            // Try the other supported layout.
+        }
+    }
+    return '0.0.0-dev';
+}

package/dist/cli/cli/vocabulary.js

@@ -0,0 +1,87 @@
+/**
+ * Canonical CLI vocabulary — orca-inspired.
+ *
+ * ONE place defines the terms the CLI uses, so help text, errors and future
+ * commands don't call the same thing by different names. `checkVocabulary`
+ * runs in tests and fails the build on drift.
+ */
+/** Canonical terms and what they mean. Add here before using a new term. */
+export const GLOSSARY = {
+    provider: 'An LLM provider configuration (API key + model), stored encrypted.',
+    gateway: 'The local BoomBot server process that serves the API and web UI.',
+    channel: 'A messaging channel integration (Telegram, Zalo, Discord, …).',
+    schedule: 'A cron-like recurring task run by the scheduler.',
+    config: 'The operator config file (~/.boombot/config.json).',
+    'data dir': 'The directory holding databases and secrets (~/.boombot).',
+};
+const TOKEN_RE = /^[a-z][a-z0-9-]*$/;
+/**
+ * Structural vocabulary checks over the live registry:
+ * - command/flag tokens are lowercase kebab-case,
+ * - no two specs claim the same spelling,
+ * - every spec has a summary + a usage line starting with `boombot `,
+ * - destructive specs must document their safety story in notes.
+ */
+export function checkVocabulary(specs) {
+    const violations = [];
+    const seen = new Map();
+    const claim = (spelling, owner) => {
+        const prev = seen.get(spelling);
+        if (prev !== undefined) {
+            violations.push({
+                where: owner,
+                problem: `spelling "${spelling}" already claimed by ${prev}`,
+            });
+        }
+        else {
+            seen.set(spelling, owner);
+        }
+    };
+    for (const spec of specs) {
+        const name = spec.path.join(' ');
+        for (const token of spec.path) {
+            if (!TOKEN_RE.test(token)) {
+                violations.push({ where: name, problem: `command token "${token}" is not kebab-case` });
+            }
+        }
+        claim(name, name);
+        for (const alias of spec.aliases ?? []) {
+            for (const token of alias) {
+                if (!TOKEN_RE.test(token)) {
+                    violations.push({
+                        where: `${name} alias`,
+                        problem: `alias token "${token}" is not kebab-case`,
+                    });
+                }
+            }
+            claim(alias.join(' '), `${name} alias`);
+        }
+        if (spec.summary.trim() === '') {
+            violations.push({ where: name, problem: 'missing summary' });
+        }
+        if (!spec.usage.startsWith('boombot ')) {
+            violations.push({ where: name, problem: `usage must start with "boombot ", got: ${spec.usage}` });
+        }
+        for (const flag of spec.flags) {
+            if (!TOKEN_RE.test(flag.name)) {
+                violations.push({ where: `${name} --${flag.name}`, problem: 'flag name is not kebab-case' });
+            }
+            if (flag.takesValue && (flag.valueName === undefined || flag.valueName.trim() === '')) {
+                violations.push({
+                    where: `${name} --${flag.name}`,
+                    problem: 'valued flag needs a valueName for usage text',
+                });
+            }
+        }
+        if (spec.destructive === true) {
+            const documented = (spec.notes ?? []).some((n) => /confirm|safety|irreversible/i.test(n));
+            if (!documented) {
+                violations.push({
+                    where: name,
+                    problem: 'destructive command must document its safety story in notes',
+                });
+            }
+        }
+    }
+    return violations;
+}