@poolzin/pool-bot 2026.2.23 → 2026.2.25

package/dist/cli/program/command-registry.js

@@ -1,170 +1,257 @@
-import { agentsListCommand } from "../../commands/agents.js";
-import { healthCommand } from "../../commands/health.js";
-import { sessionsCommand } from "../../commands/sessions.js";
-import { statusCommand } from "../../commands/status.js";
-import { defaultRuntime } from "../../runtime.js";
-import { getFlagValue, getPositiveIntFlagValue, getVerboseFlag, hasFlag } from "../argv.js";
-import { registerBrowserCli } from "../browser-cli.js";
-import { registerConfigCli } from "../config-cli.js";
-import { registerMemoryCli, runMemoryStatus } from "../memory-cli.js";
-import { registerAgentCommands } from "./register.agent.js";
-import { registerCompletionCommand } from "./register.completion.js";
-import { registerConfigureCommand } from "./register.configure.js";
-import { registerMaintenanceCommands } from "./register.maintenance.js";
-import { registerMessageCommands } from "./register.message.js";
-import { registerOnboardCommand } from "./register.onboard.js";
-import { registerSetupCommand } from "./register.setup.js";
-import { registerStatusHealthSessionsCommands } from "./register.status-health-sessions.js";
+import { getPrimaryCommand, hasHelpOrVersion } from "../argv.js";
+import { reparseProgramFromActionArgs } from "./action-reparse.js";
 import { registerSubCliCommands } from "./register.subclis.js";
-const routeHealth = {
-    match: (path) => path[0] === "health",
-    loadPlugins: true,
-    run: async (argv) => {
-        const json = hasFlag(argv, "--json");
-        const verbose = getVerboseFlag(argv, { includeDebug: true });
-        const timeoutMs = getPositiveIntFlagValue(argv, "--timeout");
-        if (timeoutMs === null)
-            return false;
-        await healthCommand({ json, timeoutMs, verbose }, defaultRuntime);
-        return true;
-    },
-};
-const routeStatus = {
-    match: (path) => path[0] === "status",
-    loadPlugins: true,
-    run: async (argv) => {
-        const json = hasFlag(argv, "--json");
-        const deep = hasFlag(argv, "--deep");
-        const all = hasFlag(argv, "--all");
-        const usage = hasFlag(argv, "--usage");
-        const verbose = getVerboseFlag(argv, { includeDebug: true });
-        const timeoutMs = getPositiveIntFlagValue(argv, "--timeout");
-        if (timeoutMs === null)
-            return false;
-        await statusCommand({ json, deep, all, usage, timeoutMs, verbose }, defaultRuntime);
-        return true;
-    },
-};
-const routeSessions = {
-    match: (path) => path[0] === "sessions",
-    run: async (argv) => {
-        const json = hasFlag(argv, "--json");
-        const store = getFlagValue(argv, "--store");
-        if (store === null)
-            return false;
-        const active = getFlagValue(argv, "--active");
-        if (active === null)
-            return false;
-        await sessionsCommand({ json, store, active }, defaultRuntime);
-        return true;
-    },
-};
-const routeAgentsList = {
-    match: (path) => path[0] === "agents" && path[1] === "list",
-    run: async (argv) => {
-        const json = hasFlag(argv, "--json");
-        const bindings = hasFlag(argv, "--bindings");
-        await agentsListCommand({ json, bindings }, defaultRuntime);
-        return true;
-    },
-};
-const routeMemoryStatus = {
-    match: (path) => path[0] === "memory" && path[1] === "status",
-    run: async (argv) => {
-        const agent = getFlagValue(argv, "--agent");
-        if (agent === null)
-            return false;
-        const json = hasFlag(argv, "--json");
-        const deep = hasFlag(argv, "--deep");
-        const index = hasFlag(argv, "--index");
-        const verbose = hasFlag(argv, "--verbose");
-        await runMemoryStatus({ agent, json, deep, index, verbose });
-        return true;
-    },
+const shouldRegisterCorePrimaryOnly = (argv) => {
+    if (hasHelpOrVersion(argv)) {
+        return false;
+    }
+    return true;
 };
-export const commandRegistry = [
-    {
-        id: "setup",
-        register: ({ program }) => registerSetupCommand(program),
-    },
-    {
-        id: "onboard",
-        register: ({ program }) => registerOnboardCommand(program),
-    },
+// Note for humans and agents:
+// If you update the list of commands, also check whether they have subcommands
+// and set the flag accordingly.
+const coreEntries = [
     {
-        id: "configure",
-        register: ({ program }) => registerConfigureCommand(program),
+        commands: [
+            {
+                name: "setup",
+                description: "Initialize local config and agent workspace",
+                hasSubcommands: false,
+            },
+        ],
+        register: async ({ program }) => {
+            const mod = await import("./register.setup.js");
+            mod.registerSetupCommand(program);
+        },
     },
     {
-        id: "completion",
-        register: ({ program }) => registerCompletionCommand(program),
+        commands: [
+            {
+                name: "onboard",
+                description: "Interactive onboarding wizard for gateway, workspace, and skills",
+                hasSubcommands: false,
+            },
+        ],
+        register: async ({ program }) => {
+            const mod = await import("./register.onboard.js");
+            mod.registerOnboardCommand(program);
+        },
     },
     {
-        id: "config",
-        register: ({ program }) => registerConfigCli(program),
+        commands: [
+            {
+                name: "configure",
+                description: "Interactive setup wizard for credentials, channels, gateway, and agent defaults",
+                hasSubcommands: false,
+            },
+        ],
+        register: async ({ program }) => {
+            const mod = await import("./register.configure.js");
+            mod.registerConfigureCommand(program);
+        },
     },
     {
-        id: "maintenance",
-        register: ({ program }) => registerMaintenanceCommands(program),
+        commands: [
+            {
+                name: "config",
+                description: "Non-interactive config helpers (get/set/unset). Default: starts setup wizard.",
+                hasSubcommands: true,
+            },
+        ],
+        register: async ({ program }) => {
+            const mod = await import("../config-cli.js");
+            mod.registerConfigCli(program);
+        },
     },
     {
-        id: "message",
-        register: ({ program, ctx }) => registerMessageCommands(program, ctx),
+        commands: [
+            {
+                name: "doctor",
+                description: "Health checks + quick fixes for the gateway and channels",
+                hasSubcommands: false,
+            },
+            {
+                name: "dashboard",
+                description: "Open the Control UI with your current token",
+                hasSubcommands: false,
+            },
+            {
+                name: "reset",
+                description: "Reset local config/state (keeps the CLI installed)",
+                hasSubcommands: false,
+            },
+            {
+                name: "uninstall",
+                description: "Uninstall the gateway service + local data (CLI remains)",
+                hasSubcommands: false,
+            },
+        ],
+        register: async ({ program }) => {
+            const mod = await import("./register.maintenance.js");
+            mod.registerMaintenanceCommands(program);
+        },
     },
     {
-        id: "memory",
-        register: ({ program }) => registerMemoryCli(program),
-        routes: [routeMemoryStatus],
+        commands: [
+            {
+                name: "message",
+                description: "Send, read, and manage messages",
+                hasSubcommands: true,
+            },
+        ],
+        register: async ({ program, ctx }) => {
+            const mod = await import("./register.message.js");
+            mod.registerMessageCommands(program, ctx);
+        },
     },
     {
-        id: "agent",
-        register: ({ program, ctx }) => registerAgentCommands(program, { agentChannelOptions: ctx.agentChannelOptions }),
-        routes: [routeAgentsList],
+        commands: [
+            {
+                name: "memory",
+                description: "Search and reindex memory files",
+                hasSubcommands: true,
+            },
+        ],
+        register: async ({ program }) => {
+            const mod = await import("../memory-cli.js");
+            mod.registerMemoryCli(program);
+        },
     },
     {
-        id: "subclis",
-        register: ({ program, argv }) => registerSubCliCommands(program, argv),
+        commands: [
+            {
+                name: "agent",
+                description: "Run one agent turn via the Gateway",
+                hasSubcommands: false,
+            },
+            {
+                name: "agents",
+                description: "Manage isolated agents (workspaces, auth, routing)",
+                hasSubcommands: true,
+            },
+        ],
+        register: async ({ program, ctx }) => {
+            const mod = await import("./register.agent.js");
+            mod.registerAgentCommands(program, {
+                agentChannelOptions: ctx.agentChannelOptions,
+            });
+        },
     },
     {
-        id: "status-health-sessions",
-        register: ({ program }) => registerStatusHealthSessionsCommands(program),
-        routes: [routeHealth, routeStatus, routeSessions],
+        commands: [
+            {
+                name: "status",
+                description: "Show channel health and recent session recipients",
+                hasSubcommands: false,
+            },
+            {
+                name: "health",
+                description: "Fetch health from the running gateway",
+                hasSubcommands: false,
+            },
+            {
+                name: "sessions",
+                description: "List stored conversation sessions",
+                hasSubcommands: false,
+            },
+        ],
+        register: async ({ program }) => {
+            const mod = await import("./register.status-health-sessions.js");
+            mod.registerStatusHealthSessionsCommands(program);
+        },
     },
     {
-        id: "browser",
-        register: ({ program }) => registerBrowserCli(program),
+        commands: [
+            {
+                name: "browser",
+                description: "Manage Pool Bot's dedicated browser (Chrome/Chromium)",
+                hasSubcommands: true,
+            },
+        ],
+        register: async ({ program }) => {
+            const mod = await import("../browser-cli.js");
+            mod.registerBrowserCli(program);
+        },
     },
 ];
+function collectCoreCliCommandNames(predicate) {
+    const seen = new Set();
+    const names = [];
+    for (const entry of coreEntries) {
+        for (const command of entry.commands) {
+            if (predicate && !predicate(command)) {
+                continue;
+            }
+            if (seen.has(command.name)) {
+                continue;
+            }
+            seen.add(command.name);
+            names.push(command.name);
+        }
+    }
+    return names;
+}
 export function getCoreCliCommandNames() {
-    return commandRegistry.flatMap((entry) => [entry.id]);
+    return collectCoreCliCommandNames();
+}
+export function getCoreCliCommandsWithSubcommands() {
+    return collectCoreCliCommandNames((command) => command.hasSubcommands);
+}
+function removeCommand(program, command) {
+    const commands = program.commands;
+    const index = commands.indexOf(command);
+    if (index >= 0) {
+        commands.splice(index, 1);
+    }
+}
+function removeEntryCommands(program, entry) {
+    // Some registrars install multiple top-level commands (e.g. status/health/sessions).
+    // Remove placeholders/old registrations for all names in the entry before re-registering.
+    for (const cmd of entry.commands) {
+        const existing = program.commands.find((c) => c.name() === cmd.name);
+        if (existing) {
+            removeCommand(program, existing);
+        }
+    }
+}
+function registerLazyCoreCommand(program, ctx, entry, command) {
+    const placeholder = program.command(command.name).description(command.description);
+    placeholder.allowUnknownOption(true);
+    placeholder.allowExcessArguments(true);
+    placeholder.action(async (...actionArgs) => {
+        removeEntryCommands(program, entry);
+        await entry.register({ program, ctx, argv: process.argv });
+        await reparseProgramFromActionArgs(program, actionArgs);
+    });
 }
 export async function registerCoreCliByName(program, ctx, name, argv = process.argv) {
-    const entry = commandRegistry.find((candidate) => candidate.id === name);
-    if (!entry)
+    const entry = coreEntries.find((candidate) => candidate.commands.some((cmd) => cmd.name === name));
+    if (!entry) {
         return false;
-    const existing = program.commands.find((c) => c.name() === name);
-    if (existing) {
-        const commands = program.commands;
-        const index = commands.indexOf(existing);
-        if (index >= 0)
-            commands.splice(index, 1);
     }
-    entry.register({ program, ctx, argv });
+    removeEntryCommands(program, entry);
+    await entry.register({ program, ctx, argv });
     return true;
 }
-export function registerProgramCommands(program, ctx, argv = process.argv) {
-    for (const entry of commandRegistry) {
-        entry.register({ program, ctx, argv });
+export function registerCoreCliCommands(program, ctx, argv) {
+    const primary = getPrimaryCommand(argv);
+    if (primary && shouldRegisterCorePrimaryOnly(argv)) {
+        const entry = coreEntries.find((candidate) => candidate.commands.some((cmd) => cmd.name === primary));
+        if (entry) {
+            const cmd = entry.commands.find((c) => c.name === primary);
+            if (cmd) {
+                registerLazyCoreCommand(program, ctx, entry, cmd);
+            }
+            return;
+        }
     }
-}
-export function findRoutedCommand(path) {
-    for (const entry of commandRegistry) {
-        if (!entry.routes)
-            continue;
-        for (const route of entry.routes) {
-            if (route.match(path))
-                return route;
+    for (const entry of coreEntries) {
+        for (const cmd of entry.commands) {
+            registerLazyCoreCommand(program, ctx, entry, cmd);
         }
     }
-    return null;
+}
+export function registerProgramCommands(program, ctx, argv = process.argv) {
+    registerCoreCliCommands(program, ctx, argv);
+    registerSubCliCommands(program, argv);
 }

package/dist/cli/program/help.js

@@ -1,9 +1,20 @@
 import { formatDocsLink } from "../../terminal/links.js";
 import { isRich, theme } from "../../terminal/theme.js";
+import { escapeRegExp } from "../../utils.js";
+import { hasFlag, hasRootVersionAlias } from "../argv.js";
 import { formatCliBannerLine, hasEmittedCliBanner } from "../banner.js";
 import { replaceCliName, resolveCliName } from "../cli-name.js";
+import { getCoreCliCommandsWithSubcommands } from "./command-registry.js";
+import { getSubCliCommandsWithSubcommands } from "./register.subclis.js";
 const CLI_NAME = resolveCliName();
+const CLI_NAME_PATTERN = escapeRegExp(CLI_NAME);
+const ROOT_COMMANDS_WITH_SUBCOMMANDS = new Set([
+    ...getCoreCliCommandsWithSubcommands(),
+    ...getSubCliCommandsWithSubcommands(),
+]);
+const ROOT_COMMANDS_HINT = "Hint: commands suffixed with * have subcommands. Run <command> --help for details.";
 const EXAMPLES = [
+    ["poolbot models --help", "Show detailed help for the models command."],
     ["poolbot channels login --verbose", "Link personal WhatsApp Web and show QR + connection logs."],
     [
         'poolbot message send --target +15555550123 --message "Hi" --json',
@@ -30,38 +41,58 @@ export function configureProgramHelp(program, ctx) {
         .option("--dev", "Dev profile: isolate state under ~/.poolbot-dev, default gateway port 19001, and shift derived ports (browser/canvas)")
         .option("--profile <name>", "Use a named profile (isolates POOLBOT_STATE_DIR/POOLBOT_CONFIG_PATH under ~/.poolbot-<name>)");
     program.option("--no-color", "Disable ANSI colors", false);
+    program.helpOption("-h, --help", "Display help for command");
+    program.helpCommand("help [command]", "Display help for command");
     program.configureHelp({
+        // sort options and subcommands alphabetically
+        sortSubcommands: true,
+        sortOptions: true,
         optionTerm: (option) => theme.option(option.flags),
-        subcommandTerm: (cmd) => theme.command(cmd.name()),
+        subcommandTerm: (cmd) => {
+            const isRootCommand = cmd.parent === program;
+            const hasSubcommands = isRootCommand && ROOT_COMMANDS_WITH_SUBCOMMANDS.has(cmd.name());
+            return theme.command(hasSubcommands ? `${cmd.name()} *` : cmd.name());
+        },
     });
+    const formatHelpOutput = (str) => {
+        let output = str;
+        const isRootHelp = new RegExp(`^Usage:\\s+${CLI_NAME_PATTERN}\\s+\\[options\\]\\s+\\[command\\]\\s*$`, "m").test(output);
+        if (isRootHelp && /^Commands:/m.test(output)) {
+            output = output.replace(/^Commands:/m, `Commands:\n  ${theme.muted(ROOT_COMMANDS_HINT)}`);
+        }
+        return output
+            .replace(/^Usage:/gm, theme.heading("Usage:"))
+            .replace(/^Options:/gm, theme.heading("Options:"))
+            .replace(/^Commands:/gm, theme.heading("Commands:"));
+    };
     program.configureOutput({
         writeOut: (str) => {
-            const colored = str
-                .replace(/^Usage:/gm, theme.heading("Usage:"))
-                .replace(/^Options:/gm, theme.heading("Options:"))
-                .replace(/^Commands:/gm, theme.heading("Commands:"));
-            process.stdout.write(colored);
+            process.stdout.write(formatHelpOutput(str));
+        },
+        writeErr: (str) => {
+            process.stderr.write(formatHelpOutput(str));
         },
-        writeErr: (str) => process.stderr.write(str),
         outputError: (str, write) => write(theme.error(str)),
     });
-    if (process.argv.includes("-V") ||
-        process.argv.includes("--version") ||
-        process.argv.includes("-v")) {
+    if (hasFlag(process.argv, "-V") ||
+        hasFlag(process.argv, "--version") ||
+        hasRootVersionAlias(process.argv)) {
         console.log(ctx.programVersion);
         process.exit(0);
     }
     program.addHelpText("beforeAll", () => {
-        if (hasEmittedCliBanner())
+        if (hasEmittedCliBanner()) {
             return "";
+        }
         const rich = isRich();
         const line = formatCliBannerLine(ctx.programVersion, { richTty: rich });
         return `\n${line}\n`;
     });
     const fmtExamples = EXAMPLES.map(([cmd, desc]) => `  ${theme.command(replaceCliName(cmd, CLI_NAME))}\n    ${theme.muted(desc)}`).join("\n");
     program.addHelpText("afterAll", ({ command }) => {
-        if (command !== program)
+        if (command !== program) {
             return "";
+        }
         const docs = formatDocsLink("/cli", "docs.molt.bot/cli");
         return `\n${theme.heading("Examples:")}\n${fmtExamples}\n\n${theme.muted("Docs:")} ${docs}\n`;
     });

package/dist/cli/route.js

@@ -5,7 +5,7 @@ import { emitCliBanner } from "./banner.js";
 import { VERSION } from "../version.js";
 import { getCommandPath, hasHelpOrVersion } from "./argv.js";
 import { ensureConfigReady } from "./program/config-guard.js";
-import { findRoutedCommand } from "./program/command-registry.js";
+import { findRoutedCommand } from "./program/routes.js";
 async function prepareRoutedCommand(params) {
     emitCliBanner(VERSION, { argv: params.argv });
     await ensureConfigReady({ runtime: defaultRuntime, commandPath: params.commandPath });

package/dist/cli/test-runtime-capture.js

@@ -0,0 +1,24 @@
+export function createCliRuntimeCapture() {
+    const runtimeLogs = [];
+    const runtimeErrors = [];
+    const stringifyArgs = (args) => args.map((value) => String(value)).join(" ");
+    return {
+        runtimeLogs,
+        runtimeErrors,
+        defaultRuntime: {
+            log: (...args) => {
+                runtimeLogs.push(stringifyArgs(args));
+            },
+            error: (...args) => {
+                runtimeErrors.push(stringifyArgs(args));
+            },
+            exit: (code) => {
+                throw new Error(`__exit__:${code}`);
+            },
+        },
+        resetRuntimeCapture: () => {
+            runtimeLogs.length = 0;
+            runtimeErrors.length = 0;
+        },
+    };
+}