Adds listCommands endpoint to a2a server (#12604)

Co-authored-by: Juanda <jdgarrido@google.com>
Co-authored-by: Shreya Keshive <shreyakeshive@google.com>

packages/a2a-server/src/commands/command-registry.test.ts

@@ -5,27 +5,44 @@
  */
 
 import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { Command } from './types.js';
 
 describe('CommandRegistry', () => {
-  const mockListExtensionsCommandInstance = {
-    names: ['extensions', 'extensions list'],
+  const mockListExtensionsCommandInstance: Command = {
+    name: 'extensions list',
+    description: 'Lists all installed extensions.',
     execute: vi.fn(),
   };
   const mockListExtensionsCommand = vi.fn(
     () => mockListExtensionsCommandInstance,
   );
 
+  const mockExtensionsCommandInstance: Command = {
+    name: 'extensions',
+    description: 'Manage extensions.',
+    execute: vi.fn(),
+    subCommands: [mockListExtensionsCommandInstance],
+  };
+  const mockExtensionsCommand = vi.fn(() => mockExtensionsCommandInstance);
+
   beforeEach(async () => {
     vi.resetModules();
-    vi.doMock('./list-extensions', () => ({
+    vi.doMock('./extensions.js', () => ({
+      ExtensionsCommand: mockExtensionsCommand,
       ListExtensionsCommand: mockListExtensionsCommand,
     }));
   });
 
-  it('should register ListExtensionsCommand on initialization', async () => {
+  it('should register ExtensionsCommand on initialization', async () => {
     const { commandRegistry } = await import('./command-registry.js');
-    expect(mockListExtensionsCommand).toHaveBeenCalled();
+    expect(mockExtensionsCommand).toHaveBeenCalled();
     const command = commandRegistry.get('extensions');
+    expect(command).toBe(mockExtensionsCommandInstance);
+  });
+
+  it('should register sub commands on initialization', async () => {
+    const { commandRegistry } = await import('./command-registry.js');
+    const command = commandRegistry.get('extensions list');
     expect(command).toBe(mockListExtensionsCommandInstance);
   });
 
@@ -37,12 +54,65 @@ describe('CommandRegistry', () => {
 
   it('register() should register a new command', async () => {
     const { commandRegistry } = await import('./command-registry.js');
-    const mockCommand = {
-      names: ['test-command'],
+    const mockCommand: Command = {
+      name: 'test-command',
+      description: '',
       execute: vi.fn(),
     };
     commandRegistry.register(mockCommand);
     const command = commandRegistry.get('test-command');
     expect(command).toBe(mockCommand);
   });
+
+  it('register() should register a nested command', async () => {
+    const { commandRegistry } = await import('./command-registry.js');
+    const mockSubSubCommand: Command = {
+      name: 'test-command-sub-sub',
+      description: '',
+      execute: vi.fn(),
+    };
+    const mockSubCommand: Command = {
+      name: 'test-command-sub',
+      description: '',
+      execute: vi.fn(),
+      subCommands: [mockSubSubCommand],
+    };
+    const mockCommand: Command = {
+      name: 'test-command',
+      description: '',
+      execute: vi.fn(),
+      subCommands: [mockSubCommand],
+    };
+    commandRegistry.register(mockCommand);
+
+    const command = commandRegistry.get('test-command');
+    const subCommand = commandRegistry.get('test-command-sub');
+    const subSubCommand = commandRegistry.get('test-command-sub-sub');
+
+    expect(command).toBe(mockCommand);
+    expect(subCommand).toBe(mockSubCommand);
+    expect(subSubCommand).toBe(mockSubSubCommand);
+  });
+
+  it('register() should not enter an infinite loop with a cyclic command', async () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const { commandRegistry } = await import('./command-registry.js');
+    const mockCommand: Command = {
+      name: 'cyclic-command',
+      description: '',
+      subCommands: [],
+      execute: vi.fn(),
+    };
+
+    mockCommand.subCommands?.push(mockCommand); // Create cycle
+
+    commandRegistry.register(mockCommand);
+
+    expect(commandRegistry.get('cyclic-command')).toBe(mockCommand);
+    expect(warnSpy).toHaveBeenCalledWith(
+      'Command cyclic-command already registered. Skipping.',
+    );
+    // If the test finishes, it means we didn't get into an infinite loop.
+    warnSpy.mockRestore();
+  });
 });

packages/a2a-server/src/commands/command-registry.ts

@@ -4,30 +4,36 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { ListExtensionsCommand } from './list-extensions.js';
-import type { Config } from '@google/gemini-cli-core';
-
-export interface Command {
-  readonly names: string[];
-  execute(config: Config, args: string[]): Promise<unknown>;
-}
+import { ExtensionsCommand } from './extensions.js';
+import type { Command } from './types.js';
 
 class CommandRegistry {
   private readonly commands = new Map<string, Command>();
 
   constructor() {
-    this.register(new ListExtensionsCommand());
+    this.register(new ExtensionsCommand());
   }
 
   register(command: Command) {
-    for (const name of command.names) {
-      this.commands.set(name, command);
+    if (this.commands.has(command.name)) {
+      console.warn(`Command ${command.name} already registered. Skipping.`);
+      return;
+    }
+
+    this.commands.set(command.name, command);
+
+    for (const subCommand of command.subCommands ?? []) {
+      this.register(subCommand);
     }
   }
 
   get(commandName: string): Command | undefined {
     return this.commands.get(commandName);
   }
+
+  getAllCommands(): Command[] {
+    return [...this.commands.values()];
+  }
 }
 
 export const commandRegistry = new CommandRegistry();

packages/a2a-server/src/commands/extensions.test.ts

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { ExtensionsCommand, ListExtensionsCommand } from './extensions.js';
+import type { Config } from '@google/gemini-cli-core';
+
+const mockListExtensions = vi.hoisted(() => vi.fn());
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const original =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+
+  return {
+    ...original,
+    listExtensions: mockListExtensions,
+  };
+});
+
+describe('ExtensionsCommand', () => {
+  it('should have the correct name', () => {
+    const command = new ExtensionsCommand();
+    expect(command.name).toEqual('extensions');
+  });
+
+  it('should have the correct description', () => {
+    const command = new ExtensionsCommand();
+    expect(command.description).toEqual('Manage extensions.');
+  });
+
+  it('should have "extensions list" as a subcommand', () => {
+    const command = new ExtensionsCommand();
+    expect(command.subCommands.map((c) => c.name)).toContain('extensions list');
+  });
+
+  it('should be a top-level command', () => {
+    const command = new ExtensionsCommand();
+    expect(command.topLevel).toBe(true);
+  });
+
+  it('should default to listing extensions', async () => {
+    const command = new ExtensionsCommand();
+    const mockConfig = {} as Config;
+    const mockExtensions = [{ name: 'ext1' }];
+    mockListExtensions.mockReturnValue(mockExtensions);
+
+    const result = await command.execute(mockConfig, []);
+
+    expect(result).toEqual({ name: 'extensions list', data: mockExtensions });
+    expect(mockListExtensions).toHaveBeenCalledWith(mockConfig);
+  });
+});
+
+describe('ListExtensionsCommand', () => {
+  it('should have the correct name', () => {
+    const command = new ListExtensionsCommand();
+    expect(command.name).toEqual('extensions list');
+  });
+
+  it('should call listExtensions with the provided config', async () => {
+    const command = new ListExtensionsCommand();
+    const mockConfig = {} as Config;
+    const mockExtensions = [{ name: 'ext1' }];
+    mockListExtensions.mockReturnValue(mockExtensions);
+
+    const result = await command.execute(mockConfig, []);
+
+    expect(result).toEqual({ name: 'extensions list', data: mockExtensions });
+    expect(mockListExtensions).toHaveBeenCalledWith(mockConfig);
+  });
+
+  it('should return a message when no extensions are installed', async () => {
+    const command = new ListExtensionsCommand();
+    const mockConfig = {} as Config;
+    mockListExtensions.mockReturnValue([]);
+
+    const result = await command.execute(mockConfig, []);
+
+    expect(result).toEqual({
+      name: 'extensions list',
+      data: 'No extensions installed.',
+    });
+    expect(mockListExtensions).toHaveBeenCalledWith(mockConfig);
+  });
+});

packages/a2a-server/src/commands/extensions.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { listExtensions, type Config } from '@google/gemini-cli-core';
+import type { Command, CommandExecutionResponse } from './types.js';
+
+export class ExtensionsCommand implements Command {
+  readonly name = 'extensions';
+  readonly description = 'Manage extensions.';
+  readonly subCommands = [new ListExtensionsCommand()];
+  readonly topLevel = true;
+
+  async execute(
+    config: Config,
+    _: string[],
+  ): Promise<CommandExecutionResponse> {
+    return new ListExtensionsCommand().execute(config, _);
+  }
+}
+
+export class ListExtensionsCommand implements Command {
+  readonly name = 'extensions list';
+  readonly description = 'Lists all installed extensions.';
+
+  async execute(
+    config: Config,
+    _: string[],
+  ): Promise<CommandExecutionResponse> {
+    const extensions = listExtensions(config);
+    const data = extensions.length ? extensions : 'No extensions installed.';
+
+    return { name: this.name, data };
+  }
+}

packages/a2a-server/src/commands/list-extensions.test.ts

@@ -1,39 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import { describe, it, expect, vi } from 'vitest';
-import { ListExtensionsCommand } from './list-extensions.js';
-import type { Config } from '@google/gemini-cli-core';
-
-const mockListExtensions = vi.hoisted(() => vi.fn());
-vi.mock('@google/gemini-cli-core', async (importOriginal) => {
-  const original =
-    await importOriginal<typeof import('@google/gemini-cli-core')>();
-
-  return {
-    ...original,
-    listExtensions: mockListExtensions,
-  };
-});
-
-describe('ListExtensionsCommand', () => {
-  it('should have the correct names', () => {
-    const command = new ListExtensionsCommand();
-    expect(command.names).toEqual(['extensions', 'extensions list']);
-  });
-
-  it('should call listExtensions with the provided config', async () => {
-    const command = new ListExtensionsCommand();
-    const mockConfig = {} as Config;
-    const mockExtensions = [{ name: 'ext1' }];
-    mockListExtensions.mockReturnValue(mockExtensions);
-
-    const result = await command.execute(mockConfig, []);
-
-    expect(result).toEqual(mockExtensions);
-    expect(mockListExtensions).toHaveBeenCalledWith(mockConfig);
-  });
-});

packages/a2a-server/src/commands/list-extensions.ts

@@ -1,16 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import { listExtensions, type Config } from '@google/gemini-cli-core';
-import type { Command } from './command-registry.js';
-
-export class ListExtensionsCommand implements Command {
-  readonly names = ['extensions', 'extensions list'];
-
-  async execute(config: Config, _: string[]): Promise<unknown> {
-    return listExtensions(config);
-  }
-}

packages/a2a-server/src/commands/types.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Config } from '@google/gemini-cli-core';
+
+export interface CommandArgument {
+  readonly name: string;
+  readonly description: string;
+  readonly isRequired?: boolean;
+}
+
+export interface Command {
+  readonly name: string;
+  readonly description: string;
+  readonly arguments?: CommandArgument[];
+  readonly subCommands?: Command[];
+  readonly topLevel?: boolean;
+
+  execute(config: Config, args: string[]): Promise<CommandExecutionResponse>;
+}
+
+export interface CommandExecutionResponse {
+  readonly name: string;
+  readonly data: unknown;
+}