@navios/commander 0.9.0 → 1.0.0-alpha.4

package/lib/index.d.cts

@@ -1,156 +1,204 @@
-import { ClassType, ClassTypeWithInstance, Container, InjectionToken, NaviosModule, Registry } from "@navios/core";
-import { ZodObject } from "zod";
+import { AbstractAdapterInterface, AdapterEnvironment, AnyInjectableType, ClassType, ClassTypeWithInstance, InjectionToken, LogLevel, ModuleMetadata, NaviosApplication, NaviosModule, Registry } from "@navios/core";
+import { ZodObject, z } from "zod";
 export * from "@navios/core";
 
-//#region src/commander.application.d.mts
+//#region src/interfaces/command-handler.interface.d.mts
 
 /**
- * Configuration options for CommanderApplication.
+ * Interface that all command classes must implement.
  *
- * @public
- */
-interface CommanderApplicationOptions {}
-/**
- * Main application class for managing CLI command execution.
+ * Commands decorated with `@Command` must implement this interface.
+ * The `execute` method is called when the command is invoked.
  *
- * This class handles module loading, command registration, and command execution.
- * It provides both programmatic and CLI-based command execution capabilities.
+ * @template TOptions - The type of options that the command accepts
  *
  * @example
  * ```typescript
- * const app = await CommanderFactory.create(AppModule)
- * await app.init()
- * await app.run(process.argv)
+ * import { Command, CommandHandler } from '@navios/commander'
+ * import { z } from 'zod'
+ *
+ * const optionsSchema = z.object({
+ *   name: z.string()
+ * })
+ *
+ * type Options = z.infer<typeof optionsSchema>
+ *
+ * @Command({ path: 'greet', optionsSchema })
+ * export class GreetCommand implements CommandHandler<Options> {
+ *   async execute(options: Options) {
+ *     console.log(`Hello, ${options.name}!`)
+ *   }
+ * }
  * ```
  */
-declare class CommanderApplication {
-  private moduleLoader;
-  private cliParser;
-  protected container: Container;
-  private appModule;
-  private options;
-  /**
-   * Indicates whether the application has been initialized.
-   * Set to `true` after `init()` is called successfully.
-   */
-  isInitialized: boolean;
-  /**
-   * @internal
-   * Sets up the application with the provided module and options.
-   * This is called automatically by CommanderFactory.create().
-   */
-  setup(appModule: ClassTypeWithInstance<NaviosModule>, options?: CommanderApplicationOptions): Promise<void>;
+interface CommandHandler<TOptions = any> {
   /**
-   * Gets the dependency injection container used by this application.
-   *
-   * @returns The Container instance
+   * Executes the command with the provided options.
    *
-   * @example
-   * ```typescript
-   * const container = app.getContainer()
-   * const service = await container.get(MyService)
-   * ```
+   * @param options - The validated command options (validated against the command's schema if provided)
+   * @returns A promise or void
    */
-  getContainer(): Container;
+  execute(options: TOptions): void | Promise<void>;
+}
+//#endregion
+//#region src/commands/help.command.d.mts
+declare const helpOptionsSchema: z.ZodObject<{
+  command: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type HelpOptions = z.infer<typeof helpOptionsSchema>;
+/**
+ * Built-in help command that lists all available commands or shows help for a specific command.
+ *
+ * @public
+ */
+declare class HelpCommand implements CommandHandler<HelpOptions> {
+  private logger;
+  private commandRegistry;
+  execute(options: HelpOptions): Promise<void>;
+}
+//#endregion
+//#region src/interfaces/abstract-cli-adapter.interface.d.mts
+/**
+ * Interface for CLI adapters.
+ * Extends the base adapter interface with CLI-specific methods.
+ *
+ * @public
+ */
+interface AbstractCliAdapterInterface extends AbstractAdapterInterface {
   /**
-   * Initializes the application by loading all modules and registering commands.
+   * Run the CLI application with the given arguments.
+   * Parses arguments and executes the matching command.
    *
-   * This method must be called before executing commands or running the CLI.
-   * It traverses the module tree, loads all imported modules, and collects command metadata.
-   *
-   * @throws {Error} If the app module is not set (setup() was not called)
+   * @param argv - Command-line arguments array (defaults to `process.argv`)
    *
    * @example
    * ```typescript
-   * const app = await CommanderFactory.create(AppModule)
-   * await app.init() // Must be called before run() or executeCommand()
+   * const adapter = app.getAdapter() as AbstractCliAdapterInterface
+   * await adapter.run(process.argv)
    * ```
    */
-  init(): Promise<void>;
+  run(argv?: string[]): Promise<void>;
   /**
-   * Executes a command programmatically with the provided options.
-   *
-   * This method is useful for testing, automation, or programmatic workflows.
-   * The options will be validated against the command's Zod schema if one is provided.
+   * Execute a command programmatically with the provided options.
    *
-   * @param commandPath - The command path (e.g., 'greet', 'user:create')
-   * @param options - The command options object (will be validated if schema exists)
-   * @throws {Error} If the application is not initialized
-   * @throws {Error} If the command is not found
-   * @throws {Error} If the command does not implement the execute method
-   * @throws {ZodError} If options validation fails
+   * @param path - The command path (e.g., 'greet', 'user:create')
+   * @param options - The command options object
    *
    * @example
    * ```typescript
-   * await app.executeCommand('greet', {
-   *   name: 'World',
-   *   greeting: 'Hi'
+   * await adapter.executeCommand('user:create', {
+   *   name: 'John',
+   *   email: 'john@example.com',
    * })
    * ```
    */
-  executeCommand(commandPath: string, options?: any): Promise<void>;
+  executeCommand(path: string, options: Record<string, unknown>): Promise<void>;
   /**
-   * Gets all registered commands with their paths and class references.
+   * Get all registered command paths and their class references.
    *
-   * @returns An array of objects containing the command path and class
+   * @returns Array of objects containing path and class
    *
    * @example
    * ```typescript
-   * const commands = app.getAllCommands()
-   * commands.forEach(({ path }) => {
-   *   console.log(`Available: ${path}`)
-   * })
+   * const commands = adapter.getAllCommands()
+   * commands.forEach(({ path }) => console.log(path))
    * ```
    */
-  getAllCommands(): {
+  getAllCommands(): Array<{
     path: string;
-    class: ClassTypeWithInstance<any>;
-  }[];
+    class: unknown;
+  }>;
+}
+//#endregion
+//#region src/interfaces/environment.interface.d.mts
+/**
+ * Options for configuring the CLI adapter.
+ *
+ * @public
+ */
+interface CliAdapterOptions {}
+/**
+ * Environment type definition for CLI adapters.
+ * Used with NaviosFactory.create<CliEnvironment>() for type-safe CLI applications.
+ *
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { NaviosFactory } from '@navios/core'
+ * import { defineCliEnvironment, type CliEnvironment } from '@navios/commander'
+ *
+ * const app = await NaviosFactory.create<CliEnvironment>(AppModule, {
+ *   adapter: defineCliEnvironment(),
+ * })
+ * ```
+ */
+interface CliEnvironment extends AdapterEnvironment {
+  options: CliAdapterOptions;
+  adapter: AbstractCliAdapterInterface;
+}
+//#endregion
+//#region src/commander.factory.d.mts
+/**
+ * Logger display options for CLI applications.
+ * All options default to false for cleaner CLI output.
+ *
+ * @public
+ */
+interface CommanderLoggerOptions {
   /**
-   * Runs the CLI application by parsing command-line arguments and executing the appropriate command.
-   *
-   * This is the main entry point for CLI usage. It parses `argv`, validates options,
-   * and executes the matching command. Supports help command (`help`, `--help`, `-h`)
-   * which displays all available commands.
-   *
-   * @param argv - Command-line arguments array (defaults to `process.argv`)
-   * @throws {Error} If the application is not initialized
-   * @throws {Error} If no command is provided
-   * @throws {Error} If the command is not found
-   * @throws {ZodError} If options validation fails
-   *
-   * @example
-   * ```typescript
-   * // Parse and execute from process.argv
-   * await app.run()
-   *
-   * // Or provide custom arguments
-   * await app.run(['node', 'cli.js', 'greet', '--name', 'World'])
-   * ```
+   * Enabled log levels.
+   * @default ['log', 'error', 'warn', 'debug', 'verbose', 'fatal']
    */
-  run(argv?: string[]): Promise<void>;
+  logLevels?: LogLevel[];
   /**
-   * @internal
-   * Disposes of resources used by the application.
+   * If true, will print the process ID in the log message.
+   * @default false
    */
-  dispose(): Promise<void>;
+  showPid?: boolean;
   /**
-   * Closes the application and cleans up resources.
-   *
-   * This should be called when the application is no longer needed to free up resources.
-   *
-   * @example
-   * ```typescript
-   * await app.run(process.argv)
-   * await app.close()
-   * ```
+   * If true, will print the log level in the log message.
+   * @default true
    */
-  close(): Promise<void>;
+  showLogLevel?: boolean;
+  /**
+   * If true, will print the prefix/app name in the log message.
+   * @default false
+   */
+  showPrefix?: boolean;
+  /**
+   * If true, will print the context in the log message.
+   * @default true
+   */
+  showContext?: boolean;
+  /**
+   * If true, will print the absolute timestamp in the log message.
+   * @default false
+   */
+  showTimestamp?: boolean;
+  /**
+   * If enabled, will print timestamp difference between current and previous log message.
+   * @default false
+   */
+  showTimeDiff?: boolean;
 }
-//#endregion
-//#region src/commander.factory.d.mts
 /**
- * Factory class for creating and configuring CLI applications.
+ * Configuration options for CommanderFactory.
+ *
+ * @public
+ */
+interface CommanderFactoryOptions {
+  /**
+   * Logger display options. These override the default CLI-friendly logger settings.
+   */
+  logger?: CommanderLoggerOptions;
+}
+/**
+ * Factory class for creating CLI applications.
+ *
+ * This is a convenience wrapper around `NaviosFactory.create()` that
+ * configures everything needed for CLI usage. It sets up the CLI adapter
+ * and returns a typed `NaviosApplication<CliEnvironment>`.
  *
  * @example
  * ```typescript
@@ -160,26 +208,43 @@ declare class CommanderApplication {
  * async function bootstrap() {
  *   const app = await CommanderFactory.create(AppModule)
  *   await app.init()
- *   await app.run(process.argv)
+ *
+ *   const adapter = app.getAdapter()
+ *   await adapter.run(process.argv)
+ *
  *   await app.close()
  * }
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Alternative: use NaviosFactory directly
+ * import { NaviosFactory } from '@navios/core'
+ * import { defineCliEnvironment, type CliEnvironment } from '@navios/commander'
+ *
+ * const app = await NaviosFactory.create<CliEnvironment>(AppModule, {
+ *   adapter: defineCliEnvironment(),
+ * })
+ * ```
  */
 declare class CommanderFactory {
   /**
-   * Creates a new CommanderApplication instance and configures it with the provided module.
+   * Creates a new CLI application instance configured with the provided module.
    *
-   * @param appModule - The root CLI module class that contains commands and/or imports other modules
-   * @param options - Optional configuration options for the application
-   * @returns A promise that resolves to a configured CommanderApplication instance
+   * @param appModule - The root CLI module class decorated with `@CliModule`
+   * @param options - Optional configuration options for the CLI application
+   * @returns A promise that resolves to a configured NaviosApplication instance
    *
    * @example
    * ```typescript
    * const app = await CommanderFactory.create(AppModule)
    * await app.init()
+   *
+   * const adapter = app.getAdapter()
+   * await adapter.run(process.argv)
    * ```
    */
-  static create(appModule: ClassTypeWithInstance<NaviosModule>, options?: CommanderApplicationOptions): Promise<CommanderApplication>;
+  static create<TModule extends NaviosModule = NaviosModule>(appModule: ClassTypeWithInstance<TModule>, options?: CommanderFactoryOptions): Promise<NaviosApplication<CliEnvironment>>;
 }
 //#endregion
 //#region src/decorators/command.decorator.d.mts
@@ -194,6 +259,11 @@ interface CommandOptions {
    * Can be a single word (e.g., 'greet') or multi-word with colons (e.g., 'user:create', 'db:migrate').
    */
   path: string;
+  /**
+   * Optional description of the command for help text.
+   * Displayed when users run `help` or `--help`.
+   */
+  description?: string;
   /**
    * Optional Zod schema for validating command options.
    * If provided, options will be validated and parsed according to this schema.
@@ -242,6 +312,7 @@ interface CommandOptions {
  */
 declare function Command({
   path,
+  description,
   optionsSchema,
   priority,
   registry
@@ -260,10 +331,27 @@ interface CliModuleOptions {
    */
   commands?: ClassType[] | Set<ClassType>;
   /**
-   * Array or Set of other CLI modules to import.
-   * Imported modules' commands will be available in this module.
+   * Array or Set of controller classes for HTTP endpoints.
+   * Allows mixing HTTP and CLI functionality in the same module.
+   */
+  controllers?: ClassType[] | Set<ClassType>;
+  /**
+   * Array or Set of other modules to import.
+   * Imported modules' commands and controllers will be available.
    */
   imports?: ClassType[] | Set<ClassType>;
+  /**
+   * Guards to apply to all controllers in this module.
+   * Guards are executed in reverse order (last guard first).
+   */
+  guards?: ClassType[] | Set<ClassType>;
+  /**
+   * Service override classes to import for side effects.
+   * These classes are imported to ensure their @Injectable decorators execute,
+   * allowing them to register with the DI system. Overrides should use the same
+   * InjectionToken as the original service with a higher priority.
+   */
+  overrides?: ClassType[] | Set<ClassType>;
   /**
    * Priority level for the module.
    * Higher priority modules will be loaded first.
@@ -278,7 +366,11 @@ interface CliModuleOptions {
 /**
  * Decorator that marks a class as a CLI module.
  *
- * Modules organize commands and can import other modules to compose larger CLI applications.
+ * This decorator extends the standard @Module decorator, adding support for
+ * CLI commands while maintaining full compatibility with HTTP controllers.
+ * Modules organize commands and can import other modules to compose larger
+ * CLI applications.
+ *
  * The module can optionally implement `NaviosModule` interface for lifecycle hooks.
  *
  * @param options - Configuration options for the module
@@ -296,50 +388,80 @@ interface CliModuleOptions {
  * })
  * export class AppModule {}
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Mixed HTTP and CLI module
+ * @CliModule({
+ *   controllers: [HealthController],
+ *   commands: [MigrateCommand],
+ *   imports: [DatabaseModule],
+ * })
+ * export class AppModule {}
+ * ```
  */
 declare function CliModule({
   commands,
+  controllers,
   imports,
+  guards,
+  overrides,
   priority,
   registry
 }?: CliModuleOptions): (target: ClassType, context: ClassDecoratorContext) => ClassType;
 //#endregion
-//#region src/interfaces/command-handler.interface.d.mts
+//#region src/services/commander-adapter.service.d.mts
 /**
- * Interface that all command classes must implement.
- *
- * Commands decorated with `@Command` must implement this interface.
- * The `execute` method is called when the command is invoked.
+ * CLI adapter service that implements the AbstractCliAdapterInterface.
+ * Handles command discovery, registration, parsing, and execution.
  *
- * @template TOptions - The type of options that the command accepts
- *
- * @example
- * ```typescript
- * import { Command, CommandHandler } from '@navios/commander'
- * import { z } from 'zod'
- *
- * const optionsSchema = z.object({
- *   name: z.string()
- * })
- *
- * type Options = z.infer<typeof optionsSchema>
- *
- * @Command({ path: 'greet', optionsSchema })
- * export class GreetCommand implements CommandHandler<Options> {
- *   async execute(options: Options) {
- *     console.log(`Hello, ${options.name}!`)
- *   }
- * }
- * ```
+ * @public
  */
-interface CommandHandler<TOptions = any> {
+declare class CommanderAdapterService implements AbstractCliAdapterInterface {
+  private container;
+  private commandRegistry;
+  private cliParser;
+  private logger;
+  private options;
+  private isReady;
   /**
-   * Executes the command with the provided options.
-   *
-   * @param options - The validated command options (validated against the command's schema if provided)
-   * @returns A promise or void
+   * Sets up the adapter with the provided options.
+   * Called during application initialization.
    */
-  execute(options: TOptions): void | Promise<void>;
+  setupAdapter(options: CliAdapterOptions): Promise<void>;
+  /**
+   * Called after all modules are loaded.
+   * Iterates through modules and extracts commands from customEntries.
+   */
+  onModulesInit(modules: Map<string, ModuleMetadata>): Promise<void>;
+  /**
+   * Registers built-in commands like help.
+   */
+  private registerBuiltInCommands;
+  /**
+   * Signals that the adapter is ready to handle commands.
+   */
+  ready(): Promise<void>;
+  /**
+   * Disposes of the adapter and cleans up resources.
+   */
+  dispose(): Promise<void>;
+  /**
+   * Run the CLI application with the given arguments.
+   * Parses arguments and executes the matching command.
+   */
+  run(argv?: string[]): Promise<void>;
+  /**
+   * Execute a command programmatically with the provided options.
+   */
+  executeCommand(path: string, options?: Record<string, unknown>): Promise<void>;
+  /**
+   * Get all registered command paths and their class references.
+   */
+  getAllCommands(): Array<{
+    path: string;
+    class: ClassType;
+  }>;
 }
 //#endregion
 //#region src/metadata/command.metadata.d.mts
@@ -358,6 +480,10 @@ interface CommandMetadata {
    * The command path (e.g., 'greet', 'user:create').
    */
   path: string;
+  /**
+   * Optional description of the command for help text.
+   */
+  description?: string;
   /**
    * Optional Zod schema for validating command options.
    */
@@ -374,10 +500,11 @@ interface CommandMetadata {
  * @param target - The command class
  * @param context - The decorator context
  * @param path - The command path
+ * @param description - Optional description for help text
  * @param optionsSchema - Optional Zod schema
  * @returns The command metadata
  */
-declare function getCommandMetadata(target: ClassType, context: ClassDecoratorContext, path: string, optionsSchema?: ZodObject): CommandMetadata;
+declare function getCommandMetadata(target: ClassType, context: ClassDecoratorContext, path: string, description?: string, optionsSchema?: ZodObject): CommandMetadata;
 /**
  * Extracts command metadata from a class.
  *
@@ -400,183 +527,123 @@ declare function extractCommandMetadata(target: ClassType): CommandMetadata;
  */
 declare function hasCommandMetadata(target: ClassType): boolean;
 //#endregion
-//#region src/interfaces/commander-execution-context.interface.d.mts
-/**
- * Execution context for a command execution.
- *
- * Provides access to command metadata, path, and validated options during command execution.
- * This context is automatically injected and available via the `CommandExecutionContext` token.
- *
- * @example
- * ```typescript
- * import { inject, Injectable } from '@navios/di'
- * import { CommandExecutionContext } from '@navios/commander'
- *
- * @Injectable()
- * class CommandLogger {
- *   private ctx = inject(CommandExecutionContext)
- *
- *   log() {
- *     console.log('Command:', this.ctx.getCommandPath())
- *     console.log('Options:', this.ctx.getOptions())
- *   }
- * }
- * ```
- */
-declare class CommanderExecutionContext {
-  private readonly command;
-  private readonly commandPath;
-  private readonly options;
-  /**
-   * @internal
-   * Creates a new execution context.
-   */
-  constructor(command: CommandMetadata, commandPath: string, options: any);
-  /**
-   * Gets the command metadata.
-   *
-   * @returns The command metadata including path and options schema
-   */
-  getCommand(): CommandMetadata;
-  /**
-   * Gets the command path that was invoked.
-   *
-   * @returns The command path (e.g., 'greet', 'user:create')
-   */
-  getCommandPath(): string;
-  /**
-   * Gets the validated command options.
-   *
-   * Options are validated against the command's Zod schema if one was provided.
-   *
-   * @returns The validated options object
-   */
-  getOptions(): any;
-}
-//#endregion
-//#region src/metadata/cli-module.metadata.d.mts
+//#region src/metadata/command-entry.metadata.d.mts
 /**
- * @internal
- * Symbol key used to store CLI module metadata on classes.
- */
-declare const CliModuleMetadataKey: unique symbol;
-/**
- * Metadata associated with a CLI module.
+ * Symbol key for storing commands in ModuleMetadata.customEntries.
+ * Used by @CliModule to store command classes.
  *
  * @public
  */
-interface CliModuleMetadata {
-  /**
-   * Set of command classes registered in this module.
-   */
-  commands: Set<ClassType>;
-  /**
-   * Set of other modules imported by this module.
-   */
-  imports: Set<ClassType>;
-  /**
-   * Map of custom attributes that can be attached to the module.
-   */
-  customAttributes: Map<string | symbol, any>;
-}
+declare const CommandEntryKey: unique symbol;
 /**
- * Gets or creates CLI module metadata for a class.
+ * Type for the command entry value stored in customEntries.
  *
- * @internal
- * @param target - The module class
- * @param context - The decorator context
- * @returns The module metadata
+ * @public
  */
-declare function getCliModuleMetadata(target: ClassType, context: ClassDecoratorContext): CliModuleMetadata;
+type CommandEntryValue = Set<ClassType>;
 /**
- * Extracts CLI module metadata from a class.
+ * Extracts commands from a module's metadata.
+ * Returns empty set if no commands are defined.
  *
- * @param target - The module class
- * @returns The module metadata
- * @throws {Error} If the class is not decorated with @CliModule
+ * @param moduleClass - The module class decorated with @CliModule or @Module
+ * @returns Set of command classes registered in the module
  *
  * @example
  * ```typescript
- * const metadata = extractCliModuleMetadata(AppModule)
- * console.log(metadata.commands.size) // Number of commands
+ * const commands = extractModuleCommands(AppModule)
+ * for (const command of commands) {
+ *   console.log(command.name)
+ * }
  * ```
  */
-declare function extractCliModuleMetadata(target: ClassType): CliModuleMetadata;
-/**
- * Checks if a class has CLI module metadata.
- *
- * @param target - The class to check
- * @returns `true` if the class is decorated with @CliModule, `false` otherwise
- */
-declare function hasCliModuleMetadata(target: ClassType): boolean;
+declare function extractModuleCommands(moduleClass: ClassType): Set<ClassType>;
 //#endregion
-//#region src/services/module-loader.service.d.mts
+//#region src/services/command-registry.service.d.mts
 /**
- * Command class with its associated metadata.
+ * Represents a registered command with its metadata and module information.
  *
  * @public
  */
-interface CommandWithMetadata {
+interface RegisteredCommand {
   /**
-   * The command class constructor.
+   * The command class
    */
-  class: ClassTypeWithInstance<CommandHandler>;
+  class: ClassType;
   /**
-   * The command metadata including path and options schema.
+   * The command metadata from @Command decorator
    */
   metadata: CommandMetadata;
+  /**
+   * Name of the module this command belongs to
+   */
+  moduleName: string;
 }
 /**
- * Service for loading and managing CLI modules and commands.
- *
- * Handles module traversal, command registration, and metadata collection.
- * This service is used internally by CommanderApplication.
+ * Service for registering and looking up CLI commands.
+ * Used internally by the CLI adapter to manage discovered commands.
  *
  * @public
  */
-declare class CliModuleLoaderService {
-  protected container: Container;
-  private modulesMetadata;
-  private loadedModules;
-  private commandsMetadata;
-  private initialized;
-  /**
-   * Loads all modules starting from the root app module.
+declare class CommandRegistryService {
+  private commands;
+  /**
+   * Register a command with its metadata.
    *
-   * Traverses the module tree, loads imported modules, and collects command metadata.
+   * @param path - The command path (e.g., 'greet', 'user:create')
+   * @param command - The registered command data
+   * @throws Error if a command with the same path is already registered
+   */
+  register(path: string, command: RegisteredCommand): void;
+  /**
+   * Get a command by its path.
    *
-   * @param appModule - The root CLI module
+   * @param path - The command path
+   * @returns The registered command or undefined if not found
    */
-  loadModules(appModule: ClassTypeWithInstance<NaviosModule>): Promise<void>;
-  private traverseModules;
-  private mergeMetadata;
+  getByPath(path: string): RegisteredCommand | undefined;
   /**
-   * Gets all loaded module metadata.
+   * Get all registered commands.
    *
-   * @returns Map of module names to their metadata
+   * @returns Map of path to registered command
    */
-  getAllModules(): Map<string, CliModuleMetadata>;
+  getAll(): Map<string, RegisteredCommand>;
   /**
-   * Gets all command classes indexed by command class name.
+   * Get all registered commands as an array of path and class pairs.
+   * Useful for listing available commands.
    *
-   * @returns Map of command class names to command classes
+   * @returns Array of objects containing path and class
    */
-  getAllCommands(): Map<string, ClassTypeWithInstance<any>>;
+  getAllAsArray(): Array<{
+    path: string;
+    class: ClassType;
+  }>;
   /**
-   * Get all commands with their metadata, indexed by command path.
-   * This is populated during loadModules, so path information is available
-   * before parsing CLI argv.
+   * Formats help text listing all available commands with descriptions.
+   *
+   * @returns Formatted string listing all commands
    */
-  getAllCommandsWithMetadata(): Map<string, CommandWithMetadata>;
+  formatCommandList(): string;
   /**
-   * Get a command by its path, with metadata already extracted.
-   * Returns undefined if command is not found.
+   * Formats help text for a specific command.
+   *
+   * @param commandPath - The command path to show help for
+   * @returns Formatted string with command help
    */
-  getCommandByPath(path: string): CommandWithMetadata | undefined;
+  formatCommandHelp(commandPath: string): string;
   /**
-   * Disposes of all loaded modules and commands, clearing internal state.
+   * Gets a human-readable type name from a Zod schema.
    */
-  dispose(): void;
+  private getSchemaTypeName;
+  /**
+   * Gets metadata from a Zod schema, traversing innerType if needed.
+   * Zod v4 stores meta at the outermost layer when .meta() is called last,
+   * or in innerType when .meta() is called before .optional()/.default().
+   */
+  private getSchemaMeta;
+  /**
+   * Clear all registered commands.
+   */
+  clear(): void;
 }
 //#endregion
 //#region src/services/cli-parser.service.d.mts
@@ -644,24 +711,95 @@ declare class CliParserService {
   private extractArrayFields;
   /**
    * Checks if a Zod schema represents a boolean type
-   * Unwraps ZodOptional and ZodDefault
+   * Unwraps ZodOptional and ZodDefault using Zod v4 API
    */
   private isSchemaBoolean;
   /**
    * Checks if a Zod schema represents an array type
-   * Unwraps ZodOptional and ZodDefault
+   * Unwraps ZodOptional and ZodDefault using Zod v4 API
    */
   private isSchemaArray;
+}
+//#endregion
+//#region src/define-environment.d.mts
+/**
+ * Defines the CLI environment configuration for use with NaviosFactory.
+ *
+ * This function returns the token mappings needed to configure a CLI application.
+ * Use it with `NaviosFactory.create()` to create a CLI application.
+ *
+ * @returns Environment configuration with token mappings
+ *
+ * @example
+ * ```typescript
+ * import { NaviosFactory } from '@navios/core'
+ * import { defineCliEnvironment, type CliEnvironment } from '@navios/commander'
+ *
+ * const app = await NaviosFactory.create<CliEnvironment>(AppModule, {
+ *   adapter: defineCliEnvironment(),
+ * })
+ * await app.init()
+ *
+ * const adapter = app.getAdapter() as AbstractCliAdapterInterface
+ * await adapter.run(process.argv)
+ * ```
+ */
+declare function defineCliEnvironment(): {
+  tokens: Map<InjectionToken<any, undefined, false>, AnyInjectableType>;
+};
+//#endregion
+//#region src/interfaces/commander-execution-context.interface.d.mts
+/**
+ * Execution context for a command execution.
+ *
+ * Provides access to command metadata, path, and validated options during command execution.
+ * This context is automatically injected and available via the `CommandExecutionContext` token.
+ *
+ * @example
+ * ```typescript
+ * import { inject, Injectable } from '@navios/core'
+ * import { CommandExecutionContext } from '@navios/commander'
+ *
+ * @Injectable()
+ * class CommandLogger {
+ *   private ctx = inject(CommandExecutionContext)
+ *
+ *   log() {
+ *     console.log('Command:', this.ctx.getCommandPath())
+ *     console.log('Options:', this.ctx.getOptions())
+ *   }
+ * }
+ * ```
+ */
+declare class CommanderExecutionContext {
+  private readonly command;
+  private readonly commandPath;
+  private readonly options;
   /**
-   * Formats help text listing all available commands.
+   * @internal
+   * Creates a new execution context.
+   */
+  constructor(command: CommandMetadata, commandPath: string, options: any);
+  /**
+   * Gets the command metadata.
    *
-   * @param commands - Array of command objects with path and class
-   * @returns Formatted string listing all commands
+   * @returns The command metadata including path and options schema
    */
-  formatCommandList(commands: Array<{
-    path: string;
-    class: any;
-  }>): string;
+  getCommand(): CommandMetadata;
+  /**
+   * Gets the command path that was invoked.
+   *
+   * @returns The command path (e.g., 'greet', 'user:create')
+   */
+  getCommandPath(): string;
+  /**
+   * Gets the validated command options.
+   *
+   * Options are validated against the command's Zod schema if one was provided.
+   *
+   * @returns The validated options object
+   */
+  getOptions(): any;
 }
 //#endregion
 //#region src/tokens/execution-context.token.d.mts
@@ -673,7 +811,7 @@ declare class CliParserService {
  *
  * @example
  * ```typescript
- * import { inject, Injectable } from '@navios/di'
+ * import { inject, Injectable } from '@navios/core'
  * import { CommandExecutionContext } from '@navios/commander'
  *
  * @Injectable()
@@ -690,5 +828,5 @@ declare class CliParserService {
  */
 declare const CommandExecutionContext: InjectionToken<CommanderExecutionContext, undefined, false>;
 //#endregion
-export { CliModule, CliModuleLoaderService, CliModuleMetadata, CliModuleMetadataKey, CliModuleOptions, CliParserService, Command, CommandExecutionContext, CommandHandler, CommandMetadata, CommandMetadataKey, CommandOptions, CommandWithMetadata, CommanderApplication, CommanderApplicationOptions, CommanderExecutionContext, CommanderFactory, ParsedCliArgs, extractCliModuleMetadata, extractCommandMetadata, getCliModuleMetadata, getCommandMetadata, hasCliModuleMetadata, hasCommandMetadata };
+export { AbstractCliAdapterInterface, CliAdapterOptions, CliEnvironment, CliModule, CliModuleOptions, CliParserService, Command, CommandEntryKey, CommandEntryValue, CommandExecutionContext, CommandHandler, CommandMetadata, CommandMetadataKey, CommandOptions, CommandRegistryService, CommanderAdapterService, CommanderExecutionContext, CommanderFactory, CommanderFactoryOptions, CommanderLoggerOptions, HelpCommand, ParsedCliArgs, RegisteredCommand, defineCliEnvironment, extractCommandMetadata, extractModuleCommands, getCommandMetadata, hasCommandMetadata };
 //# sourceMappingURL=index.d.cts.map