Plugins/CLI: add descriptor-backed lazy root command registration (#57165)

Merged via squash.

Prepared head SHA: ad1dee32eb
Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com>
Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com>
Reviewed-by: @gumadeiras

src/plugins/cli.test.ts

@@ -5,6 +5,7 @@ import type { OpenClawConfig } from "../config/config.js";
 const mocks = vi.hoisted(() => ({
   memoryRegister: vi.fn(),
   otherRegister: vi.fn(),
+  memoryListAction: vi.fn(),
   loadOpenClawPlugins: vi.fn(),
   applyPluginAutoEnable: vi.fn(),
 }));
@@ -27,19 +28,34 @@ function createProgram(existingCommandName?: string) {
   return program;
 }
 
-function createCliRegistry() {
+function createCliRegistry(params?: {
+  memoryCommands?: string[];
+  memoryDescriptors?: Array<{
+    name: string;
+    description: string;
+    hasSubcommands: boolean;
+  }>;
+}) {
   return {
     cliRegistrars: [
       {
         pluginId: "memory-core",
         register: mocks.memoryRegister,
-        commands: ["memory"],
+        commands: params?.memoryCommands ?? ["memory"],
+        descriptors: params?.memoryDescriptors ?? [
+          {
+            name: "memory",
+            description: "Memory commands",
+            hasSubcommands: true,
+          },
+        ],
         source: "bundled",
       },
       {
         pluginId: "other",
         register: mocks.otherRegister,
         commands: ["other"],
+        descriptors: [],
         source: "bundled",
       },
     ],
@@ -81,51 +97,37 @@ function expectAutoEnabledCliLoad(params: {
   expectPluginLoaderConfig(params.autoEnabledConfig);
 }
 
-function expectCliRegistrarCalledWithConfig(config: OpenClawConfig) {
-  expect(mocks.memoryRegister).toHaveBeenCalledWith(
-    expect.objectContaining({
-      config,
-    }),
-  );
-}
-
-function runRegisterPluginCliCommands(params: {
-  existingCommandName?: string;
-  config: OpenClawConfig;
-  env?: NodeJS.ProcessEnv;
-}) {
-  const program = createProgram(params.existingCommandName);
-  registerPluginCliCommands(program, params.config, params.env);
-  return program;
-}
-
 describe("registerPluginCliCommands", () => {
   beforeEach(() => {
-    mocks.memoryRegister.mockClear();
-    mocks.otherRegister.mockClear();
+    mocks.memoryRegister.mockReset();
+    mocks.memoryRegister.mockImplementation(({ program }: { program: Command }) => {
+      const memory = program.command("memory").description("Memory commands");
+      memory.command("list").action(mocks.memoryListAction);
+    });
+    mocks.otherRegister.mockReset();
+    mocks.otherRegister.mockImplementation(({ program }: { program: Command }) => {
+      program.command("other").description("Other commands");
+    });
+    mocks.memoryListAction.mockReset();
     mocks.loadOpenClawPlugins.mockReset();
     mocks.loadOpenClawPlugins.mockReturnValue(createCliRegistry());
     mocks.applyPluginAutoEnable.mockReset();
     mocks.applyPluginAutoEnable.mockImplementation(({ config }) => ({ config, changes: [] }));
   });
 
-  it("skips plugin CLI registrars when commands already exist", () => {
-    runRegisterPluginCliCommands({
-      existingCommandName: "memory",
-      config: {} as OpenClawConfig,
-    });
+  it("skips plugin CLI registrars when commands already exist", async () => {
+    const program = createProgram("memory");
+
+    await registerPluginCliCommands(program, {} as OpenClawConfig);
 
     expect(mocks.memoryRegister).not.toHaveBeenCalled();
     expect(mocks.otherRegister).toHaveBeenCalledTimes(1);
   });
 
-  it("forwards an explicit env to plugin loading", () => {
+  it("forwards an explicit env to plugin loading", async () => {
     const env = { OPENCLAW_HOME: "/srv/openclaw-home" } as NodeJS.ProcessEnv;
 
-    runRegisterPluginCliCommands({
-      config: {} as OpenClawConfig,
-      env,
-    });
+    await registerPluginCliCommands(createProgram(), {} as OpenClawConfig, env);
 
     expect(mocks.loadOpenClawPlugins).toHaveBeenCalledWith(
       expect.objectContaining({
@@ -134,15 +136,77 @@ describe("registerPluginCliCommands", () => {
     );
   });
 
-  it("loads plugin CLI commands from the auto-enabled config snapshot", () => {
+  it("loads plugin CLI commands from the auto-enabled config snapshot", async () => {
     const { rawConfig, autoEnabledConfig } = createAutoEnabledCliFixture();
     mocks.applyPluginAutoEnable.mockReturnValue({ config: autoEnabledConfig, changes: [] });
 
-    runRegisterPluginCliCommands({
-      config: rawConfig,
-    });
+    await registerPluginCliCommands(createProgram(), rawConfig);
 
     expectAutoEnabledCliLoad({ rawConfig, autoEnabledConfig });
-    expectCliRegistrarCalledWithConfig(autoEnabledConfig);
+    expect(mocks.memoryRegister).toHaveBeenCalledWith(
+      expect.objectContaining({
+        config: autoEnabledConfig,
+      }),
+    );
+  });
+
+  it("lazy-registers descriptor-backed plugin commands on first invocation", async () => {
+    const program = createProgram();
+    program.exitOverride();
+
+    await registerPluginCliCommands(program, {} as OpenClawConfig, undefined, undefined, {
+      mode: "lazy",
+    });
+
+    expect(program.commands.map((command) => command.name())).toEqual(["memory", "other"]);
+    expect(mocks.memoryRegister).not.toHaveBeenCalled();
+    expect(mocks.otherRegister).toHaveBeenCalledTimes(1);
+
+    await program.parseAsync(["memory", "list"], { from: "user" });
+
+    expect(mocks.memoryRegister).toHaveBeenCalledTimes(1);
+    expect(mocks.memoryListAction).toHaveBeenCalledTimes(1);
+  });
+
+  it("falls back to eager registration when descriptors do not cover every command root", async () => {
+    mocks.loadOpenClawPlugins.mockReturnValue(
+      createCliRegistry({
+        memoryCommands: ["memory", "memory-admin"],
+        memoryDescriptors: [
+          {
+            name: "memory",
+            description: "Memory commands",
+            hasSubcommands: true,
+          },
+        ],
+      }),
+    );
+    mocks.memoryRegister.mockImplementation(({ program }: { program: Command }) => {
+      program.command("memory");
+      program.command("memory-admin");
+    });
+
+    await registerPluginCliCommands(createProgram(), {} as OpenClawConfig, undefined, undefined, {
+      mode: "lazy",
+    });
+
+    expect(mocks.memoryRegister).toHaveBeenCalledTimes(1);
+  });
+
+  it("registers a selected plugin primary eagerly during lazy startup", async () => {
+    const program = createProgram();
+    program.exitOverride();
+
+    await registerPluginCliCommands(program, {} as OpenClawConfig, undefined, undefined, {
+      mode: "lazy",
+      primary: "memory",
+    });
+
+    expect(program.commands.filter((command) => command.name() === "memory")).toHaveLength(1);
+
+    await program.parseAsync(["memory", "list"], { from: "user" });
+
+    expect(mocks.memoryRegister).toHaveBeenCalledTimes(1);
+    expect(mocks.memoryListAction).toHaveBeenCalledTimes(1);
   });
 });