@navios/commander 0.9.0 → 1.0.0-alpha.4

package/CHANGELOG.md

@@ -5,6 +5,79 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.0-alpha.4] - 2026-01-09
+
+### Added
+
+- **Unified Adapter Architecture**: Commander now uses the unified adapter system from `@navios/core`
+  - `CommanderAdapterService` implements `AbstractCliAdapterInterface` with standard lifecycle methods
+  - `AbstractCliAdapterInterface` extends `AbstractAdapterInterface` with CLI-specific methods (`run`, `executeCommand`, `getAllCommands`)
+  - `CliEnvironment` interface for type-safe CLI configuration
+  - `defineCommanderEnvironment()` function for creating CLI adapter environments
+- **Command Description Support**: Commands now support `description` property for help text
+  - `@Command({ path: 'greet', description: 'Greet a user' })`
+  - Descriptions displayed in `--help` output
+- **Built-in Help Command**: Automatic `help` command with `--help` flag support
+  - Shows all available commands with descriptions
+  - Per-command help with option details from Zod schema metadata
+  - Supports `.meta({ description: '...' })` on Zod fields for option descriptions
+- **Command Registry Service**: New `CommandRegistryService` for managing registered commands
+  - Replaces module-level command tracking
+  - Provides `register()`, `getByPath()`, `getAllAsArray()`, and `clear()` methods
+- **Module Custom Entries**: Commands are now registered via `customEntries` in module metadata
+  - `@CliModule({ commands: [...] })` stores commands in `customEntries` Map
+  - Adapter discovers commands via `CommandEntryKey` in module metadata
+
+### Changed
+
+- **Factory Returns NaviosApplication**: `CommanderFactory.create()` now returns `NaviosApplication` instead of `CommanderApplication`
+  - Use `app.getAdapter()` to access CLI-specific methods
+  - Aligns with HTTP adapter pattern for consistency
+- **CLI Module Decorator**: `@CliModule()` now extends `@Module()` with command registration
+  - Commands are added to `customEntries` instead of separate metadata
+  - Module imports and providers work the same as `@Module()`
+- **Command Decorator**: Now stores metadata using standard Navios metadata system
+  - Metadata includes `description` field for help text
+- **Application Lifecycle**: Uses standard `NaviosApplication` lifecycle
+  - `app.init()` initializes modules and adapter
+  - `app.getAdapter().run()` executes CLI commands
+  - `app.close()` disposes resources
+
+### Removed
+
+- **CommanderApplication Class**: Replaced by `NaviosApplication` with CLI adapter
+- **CliModuleLoaderService**: Replaced by `CommanderAdapterService.onModulesInit()`
+- **CliModuleMetadata**: Module metadata now uses standard `ModuleMetadata` with `customEntries`
+
+### Breaking Changes
+
+- **Factory Return Type**: `CommanderFactory.create()` returns `NaviosApplication` instead of `CommanderApplication`
+  - Before: `const app = await CommanderFactory.create(AppModule); await app.run()`
+  - After: `const app = await CommanderFactory.create(AppModule); await app.init(); await app.getAdapter().run()`
+- **Method Access**: CLI methods accessed via `app.getAdapter()` instead of directly on app
+  - Before: `app.executeCommand('greet', opts)`
+  - After: `app.getAdapter().executeCommand('greet', opts)`
+- **Module Decorator**: `@CliModule()` decorator signature unchanged but internal metadata format changed
+
+### Dependencies
+
+- Updated to support `@navios/core` ^1.0.0-alpha.4
+
+## [1.0.0-alpha.2] - 2026-01-07
+
+### Added
+
+- **Module Overrides**: New `overrides` option in `@CliModule()` decorator for service override classes
+  - Service override classes are imported for side effects to ensure their `@Injectable` decorators execute
+  - Overrides should use the same `InjectionToken` as the original service with a higher priority
+  - `CliModuleLoaderService` validates overrides and logs warnings if override is not active or not registered
+  - Mirrors the same functionality as `@Module()` in `@navios/core`
+- **Logger Integration**: `CliModuleLoaderService` now uses the `Logger` service for consistent logging
+
+### Dependencies
+
+- Updated to support `@navios/core` ^1.0.0-alpha.2
+
 ## [0.9.0] - 2025-12-23
 
 ### Dependencies

package/README.md

@@ -1,19 +1,20 @@
 # @navios/commander
 
-A CLI command framework built on `@navios/di` that provides a decorator-based approach to building command-line applications, similar to how `@navios/core` works for HTTP applications.
+A CLI command framework built on `@navios/core` that provides a decorator-based approach to building command-line applications. It uses the same patterns and architecture as Navios HTTP applications, making it easy to share code and services between your CLI tools and web servers.
 
 ## Installation
 
 ```bash
-npm install @navios/commander @navios/di zod
+npm install @navios/commander zod
 ```
 
 ## Features
 
 - **Decorator-based**: Use `@Command` and `@CliModule` decorators to define commands and modules
-- **Dependency Injection**: Full integration with `@navios/di`
+- **Dependency Injection**: Full DI support via `@navios/core` with request-scoped command execution
 - **Schema Validation**: Built-in support for Zod schemas to validate command options
 - **Modular Architecture**: Organize commands into modules with imports support
+- **Built-in Help**: Automatic `help` command and `--help` flag support with Zod meta descriptions
 
 ## Usage
 
@@ -27,14 +28,15 @@ import { Command, CommandHandler } from '@navios/commander'
 import { z } from 'zod'
 
 const greetOptionsSchema = z.object({
-  name: z.string(),
-  greeting: z.string().optional().default('Hello'),
+  name: z.string().meta({ description: 'Name of the person to greet' }),
+  greeting: z.string().optional().default('Hello').meta({ description: 'Greeting message' }),
 })
 
 type GreetOptions = z.infer<typeof greetOptionsSchema>
 
 @Command({
   path: 'greet',
+  description: 'Greet a user with a custom message',
   optionsSchema: greetOptionsSchema,
 })
 export class GreetCommand implements CommandHandler<GreetOptions> {
@@ -55,6 +57,8 @@ import { GreetCommand } from './greet.command'
 
 @CliModule({
   commands: [GreetCommand],
+  // Optional: overrides for service implementations with higher priority
+  // overrides: [OverrideService],
 })
 export class AppModule {}
 ```
@@ -72,8 +76,9 @@ async function bootstrap() {
   const app = await CommanderFactory.create(AppModule)
   await app.init()
 
-  // Run with command-line arguments
-  await app.run(process.argv)
+  // Get the adapter and run with command-line arguments
+  const adapter = app.getAdapter()
+  await adapter.run(process.argv)
 
   await app.close()
 }
@@ -90,8 +95,13 @@ node dist/cli.js greet --name World --greeting Hi
 ### Advanced Example with Dependency Injection
 
 ```typescript
-import { CliModule, Command, CommandHandler } from '@navios/commander'
-import { inject, Injectable } from '@navios/di'
+import {
+  CliModule,
+  Command,
+  CommandHandler,
+  inject,
+  Injectable,
+} from '@navios/commander'
 
 import { z } from 'zod'
 
@@ -140,8 +150,13 @@ export class AppModule {}
 The `ExecutionContext` provides access to the current command execution information, including the module metadata, command metadata, command path, and options. This is useful for middleware, guards, or any service that needs context about the current command execution.
 
 ```typescript
-import { Command, CommandHandler, CommandExecutionContext } from '@navios/commander'
-import { inject, Injectable } from '@navios/di'
+import {
+  Command,
+  CommandExecutionContext,
+  CommandHandler,
+  inject,
+  Injectable,
+} from '@navios/commander'
 
 @Injectable()
 class CommandLogger {
@@ -178,7 +193,8 @@ The `ExecutionContext` provides the following methods:
 const app = await CommanderFactory.create(AppModule)
 await app.init()
 
-const commands = app.getAllCommands()
+const adapter = app.getAdapter()
+const commands = adapter.getAllCommands()
 console.log('Available commands:')
 commands.forEach(({ path }) => {
   console.log(`  - ${path}`)
@@ -201,7 +217,8 @@ async function bootstrap() {
   await app.init()
 
   // Execute a command programmatically
-  await app.executeCommand('greet', {
+  const adapter = app.getAdapter()
+  await adapter.executeCommand('greet', {
     name: 'World',
     greeting: 'Hi',
   })
@@ -229,6 +246,7 @@ Defines a CLI command.
 **Options:**
 
 - `path: string` - The command path (e.g., 'user:create', 'db:migrate')
+- `description?: string` - Optional description for help text
 - `optionsSchema?: ZodSchema` - Optional Zod schema for validating command options
 
 #### `@CliModule(options)`
@@ -239,6 +257,7 @@ Defines a CLI module.
 
 - `commands?: ClassType[]` - Array of command classes
 - `imports?: ClassType[]` - Array of other modules to import
+- `overrides?: ClassType[]` - Array of service override classes to import for side effects (ensures `@Injectable` decorators execute)
 
 ### Interfaces
 
@@ -272,19 +291,27 @@ Factory class for creating CLI applications.
 
 - `static async create(appModule, options?)` - Creates a new CommanderApplication
 
-#### `CommanderApplication`
+#### `NaviosApplication`
 
-Main application class.
+Main application class returned by `CommanderFactory.create()`.
 
 **Methods:**
 
 - `async init()` - Initializes the application
-- `async run(argv)` - Parses command-line arguments and executes the appropriate command (default usage)
-- `async executeCommand(path, options?)` - Executes a command programmatically with options (advanced usage)
-- `getAllCommands()` - Returns all registered commands
+- `getAdapter()` - Returns the CLI adapter for running commands
 - `getContainer()` - Returns the DI container
 - `async close()` - Closes the application
 
+#### `AbstractCliAdapterInterface`
+
+CLI adapter interface returned by `app.getAdapter()`.
+
+**Methods:**
+
+- `async run(argv)` - Parses command-line arguments and executes the appropriate command
+- `async executeCommand(path, options?)` - Executes a command programmatically with options
+- `getAllCommands()` - Returns all registered commands
+
 ## License
 
 MIT

package/dist/src/commander.factory.d.mts

@@ -1,8 +1,65 @@
-import type { ClassTypeWithInstance, NaviosModule } from '@navios/core';
-import type { CommanderApplicationOptions } from './commander.application.mjs';
-import { CommanderApplication } from './commander.application.mjs';
+import type { ClassTypeWithInstance, LogLevel, NaviosApplication, NaviosModule } from '@navios/core';
+import type { CliEnvironment } from './interfaces/environment.interface.mjs';
 /**
- * Factory class for creating and configuring CLI applications.
+ * Logger display options for CLI applications.
+ * All options default to false for cleaner CLI output.
+ *
+ * @public
+ */
+export interface CommanderLoggerOptions {
+    /**
+     * Enabled log levels.
+     * @default ['log', 'error', 'warn', 'debug', 'verbose', 'fatal']
+     */
+    logLevels?: LogLevel[];
+    /**
+     * If true, will print the process ID in the log message.
+     * @default false
+     */
+    showPid?: boolean;
+    /**
+     * If true, will print the log level in the log message.
+     * @default true
+     */
+    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;
+}
+/**
+ * Configuration options for CommanderFactory.
+ *
+ * @public
+ */
+export 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
@@ -12,25 +69,42 @@ import { CommanderApplication } from './commander.application.mjs';
  * 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(),
+ * })
+ * ```
  */
 export 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>>;
 }
 //# sourceMappingURL=commander.factory.d.mts.map

package/dist/src/commander.factory.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"commander.factory.d.mts","sourceRoot":"","sources":["../../src/commander.factory.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAIvE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAA;AAE9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAA;AAElE;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,gBAAgB;IAC3B;;;;;;;;;;;;OAYG;WACU,MAAM,CACjB,SAAS,EAAE,qBAAqB,CAAC,YAAY,CAAC,EAC9C,OAAO,GAAE,2BAAgC;CAO5C"}
+{"version":3,"file":"commander.factory.d.mts","sourceRoot":"","sources":["../../src/commander.factory.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EACrB,QAAQ,EACR,iBAAiB,EACjB,YAAY,EACb,MAAM,cAAc,CAAA;AAIrB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAA;AAI5E;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAA;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,MAAM,CAAC,EAAE,sBAAsB,CAAA;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,gBAAgB;IAC3B;;;;;;;;;;;;;;;OAeG;WACU,MAAM,CAAC,OAAO,SAAS,YAAY,GAAG,YAAY,EAC7D,SAAS,EAAE,qBAAqB,CAAC,OAAO,CAAC,EACzC,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,iBAAiB,CAAC,cAAc,CAAC,CAAC;CAgB9C"}

package/dist/src/commands/help.command.d.mts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import type { CommandHandler } from '../interfaces/command-handler.interface.mjs';
+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
+ */
+export declare class HelpCommand implements CommandHandler<HelpOptions> {
+    private logger;
+    private commandRegistry;
+    execute(options: HelpOptions): Promise<void>;
+}
+export {};
+//# sourceMappingURL=help.command.d.mts.map

package/dist/src/commands/help.command.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.command.d.mts","sourceRoot":"","sources":["../../../src/commands/help.command.mts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6CAA6C,CAAA;AAKjF,QAAA,MAAM,iBAAiB;;iBAErB,CAAA;AAEF,KAAK,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAEpD;;;;GAIG;AACH,qBAKa,WAAY,YAAW,cAAc,CAAC,WAAW,CAAC;IAC7D,OAAO,CAAC,MAAM,CAA2C;IACzD,OAAO,CAAC,eAAe,CAAiC;IAElD,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CAOnD"}

package/dist/src/commands/index.d.mts

@@ -0,0 +1,2 @@
+export * from './help.command.mjs';
+//# sourceMappingURL=index.d.mts.map

package/dist/src/commands/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../../src/commands/index.mts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAA"}

package/dist/src/decorators/cli-module.decorator.d.mts

@@ -11,10 +11,27 @@ export 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.
@@ -29,7 +46,11 @@ export 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
@@ -47,6 +68,17 @@ export interface CliModuleOptions {
  * })
  * export class AppModule {}
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Mixed HTTP and CLI module
+ * @CliModule({
+ *   controllers: [HealthController],
+ *   commands: [MigrateCommand],
+ *   imports: [DatabaseModule],
+ * })
+ * export class AppModule {}
+ * ```
  */
-export declare function CliModule({ commands, imports, priority, registry }?: CliModuleOptions): (target: ClassType, context: ClassDecoratorContext) => ClassType;
+export declare function CliModule({ commands, controllers, imports, guards, overrides, priority, registry, }?: CliModuleOptions): (target: ClassType, context: ClassDecoratorContext) => ClassType;
 //# sourceMappingURL=cli-module.decorator.d.mts.map

package/dist/src/decorators/cli-module.decorator.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-module.decorator.d.mts","sourceRoot":"","sources":["../../../src/decorators/cli-module.decorator.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAMvD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,EAAE,GAAG,GAAG,CAAC,SAAS,CAAC,CAAA;IACvC;;;OAGG;IACH,OAAO,CAAC,EAAE,SAAS,EAAE,GAAG,GAAG,CAAC,SAAS,CAAC,CAAA;IACtC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CACvB,EAAE,QAAa,EAAE,OAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAE,gBAGpD,IAEO,QAAQ,SAAS,EAAE,SAAS,qBAAqB,eAuB1D"}
+{"version":3,"file":"cli-module.decorator.d.mts","sourceRoot":"","sources":["../../../src/decorators/cli-module.decorator.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AASvD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,EAAE,GAAG,GAAG,CAAC,SAAS,CAAC,CAAA;IACvC;;;OAGG;IACH,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,GAAG,CAAC,SAAS,CAAC,CAAA;IAC1C;;;OAGG;IACH,OAAO,CAAC,EAAE,SAAS,EAAE,GAAG,GAAG,CAAC,SAAS,CAAC,CAAA;IACtC;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,GAAG,CAAC,SAAS,CAAC,CAAA;IACrC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,EAAE,GAAG,GAAG,CAAC,SAAS,CAAC,CAAA;IACxC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,SAAS,CACvB,EACE,QAAa,EACb,WAAgB,EAChB,OAAY,EACZ,MAAW,EACX,SAAc,EACd,QAAQ,EACR,QAAQ,GACT,GAAE,gBAMF,IAEO,QAAQ,SAAS,EAAE,SAAS,qBAAqB,eAgC1D"}

package/dist/src/decorators/command.decorator.d.mts

@@ -11,6 +11,11 @@ export 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.
@@ -57,5 +62,5 @@ export interface CommandOptions {
  * }
  * ```
  */
-export declare function Command({ path, optionsSchema, priority, registry, }: CommandOptions): (target: ClassType, context: ClassDecoratorContext) => ClassType;
+export declare function Command({ path, description, optionsSchema, priority, registry, }: CommandOptions): (target: ClassType, context: ClassDecoratorContext) => ClassType;
 //# sourceMappingURL=command.decorator.d.mts.map

package/dist/src/decorators/command.decorator.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"command.decorator.d.mts","sourceRoot":"","sources":["../../../src/decorators/command.decorator.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAA;AAMpC;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,aAAa,CAAC,EAAE,SAAS,CAAA;IACzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,OAAO,CAAC,EACtB,IAAI,EACJ,aAAa,EACb,QAAQ,EACR,QAAQ,GACT,EAAE,cAAc,IACE,QAAQ,SAAS,EAAE,SAAS,qBAAqB,eAiBnE"}
+{"version":3,"file":"command.decorator.d.mts","sourceRoot":"","sources":["../../../src/decorators/command.decorator.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAA;AAMpC;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,aAAa,CAAC,EAAE,SAAS,CAAA;IACzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,OAAO,CAAC,EACtB,IAAI,EACJ,WAAW,EACX,aAAa,EACb,QAAQ,EACR,QAAQ,GACT,EAAE,cAAc,IACE,QAAQ,SAAS,EAAE,SAAS,qBAAqB,eAiBnE"}

package/dist/src/define-environment.d.mts

@@ -0,0 +1,31 @@
+import type { AnyInjectableType, InjectionToken } from '@navios/core';
+import { CommanderAdapterService } from './services/commander-adapter.service.mjs';
+import { CommandRegistryService } from './services/command-registry.service.mjs';
+import { CliParserService } from './services/cli-parser.service.mjs';
+/**
+ * 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)
+ * ```
+ */
+export declare function defineCliEnvironment(): {
+    tokens: Map<InjectionToken<any, undefined, false>, AnyInjectableType>;
+};
+export { CommanderAdapterService, CommandRegistryService, CliParserService };
+//# sourceMappingURL=define-environment.d.mts.map

package/dist/src/define-environment.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-environment.d.mts","sourceRoot":"","sources":["../../src/define-environment.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAIrE,OAAO,EAAE,uBAAuB,EAAE,MAAM,0CAA0C,CAAA;AAClF,OAAO,EAAE,sBAAsB,EAAE,MAAM,yCAAyC,CAAA;AAChF,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAA;AAEpE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB;;EAKnC;AAGD,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,CAAA"}

package/dist/src/index.d.mts

@@ -1,7 +1,8 @@
 export * from '@navios/core';
-export * from './commander.application.mjs';
+export * from './commands/index.mjs';
 export * from './commander.factory.mjs';
 export * from './decorators/index.mjs';
+export * from './define-environment.mjs';
 export * from './interfaces/index.mjs';
 export * from './metadata/index.mjs';
 export * from './services/index.mjs';

package/dist/src/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../src/index.mts"],"names":[],"mappings":"AACA,cAAc,cAAc,CAAA;AAG5B,cAAc,6BAA6B,CAAA;AAC3C,cAAc,yBAAyB,CAAA;AACvC,cAAc,wBAAwB,CAAA;AACtC,cAAc,wBAAwB,CAAA;AACtC,cAAc,sBAAsB,CAAA;AACpC,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../src/index.mts"],"names":[],"mappings":"AACA,cAAc,cAAc,CAAA;AAG5B,cAAc,sBAAsB,CAAA;AACpC,cAAc,yBAAyB,CAAA;AACvC,cAAc,wBAAwB,CAAA;AACtC,cAAc,0BAA0B,CAAA;AACxC,cAAc,wBAAwB,CAAA;AACtC,cAAc,sBAAsB,CAAA;AACpC,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA"}

package/dist/src/interfaces/abstract-cli-adapter.interface.d.mts

@@ -0,0 +1,53 @@
+import type { AbstractAdapterInterface } from '@navios/core';
+/**
+ * Interface for CLI adapters.
+ * Extends the base adapter interface with CLI-specific methods.
+ *
+ * @public
+ */
+export interface AbstractCliAdapterInterface extends AbstractAdapterInterface {
+    /**
+     * Run the CLI application with the given arguments.
+     * Parses arguments and executes the matching command.
+     *
+     * @param argv - Command-line arguments array (defaults to `process.argv`)
+     *
+     * @example
+     * ```typescript
+     * const adapter = app.getAdapter() as AbstractCliAdapterInterface
+     * await adapter.run(process.argv)
+     * ```
+     */
+    run(argv?: string[]): Promise<void>;
+    /**
+     * Execute a command programmatically with the provided options.
+     *
+     * @param path - The command path (e.g., 'greet', 'user:create')
+     * @param options - The command options object
+     *
+     * @example
+     * ```typescript
+     * await adapter.executeCommand('user:create', {
+     *   name: 'John',
+     *   email: 'john@example.com',
+     * })
+     * ```
+     */
+    executeCommand(path: string, options: Record<string, unknown>): Promise<void>;
+    /**
+     * Get all registered command paths and their class references.
+     *
+     * @returns Array of objects containing path and class
+     *
+     * @example
+     * ```typescript
+     * const commands = adapter.getAllCommands()
+     * commands.forEach(({ path }) => console.log(path))
+     * ```
+     */
+    getAllCommands(): Array<{
+        path: string;
+        class: unknown;
+    }>;
+}
+//# sourceMappingURL=abstract-cli-adapter.interface.d.mts.map

package/dist/src/interfaces/abstract-cli-adapter.interface.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract-cli-adapter.interface.d.mts","sourceRoot":"","sources":["../../../src/interfaces/abstract-cli-adapter.interface.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAA;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,2BAA4B,SAAQ,wBAAwB;IAC3E;;;;;;;;;;;OAWG;IACH,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEnC;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE7E;;;;;;;;;;OAUG;IACH,cAAc,IAAI,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;CAC1D"}

package/dist/src/interfaces/commander-execution-context.interface.d.mts

@@ -7,7 +7,7 @@ import type { CommandMetadata } from '../metadata/command.metadata.mjs';
  *
  * @example
  * ```typescript
- * import { inject, Injectable } from '@navios/di'
+ * import { inject, Injectable } from '@navios/core'
  * import { CommandExecutionContext } from '@navios/commander'
  *
  * @Injectable()

package/dist/src/interfaces/environment.interface.d.mts

@@ -0,0 +1,30 @@
+import type { AdapterEnvironment } from '@navios/core';
+import type { AbstractCliAdapterInterface } from './abstract-cli-adapter.interface.mjs';
+/**
+ * Options for configuring the CLI adapter.
+ *
+ * @public
+ */
+export 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(),
+ * })
+ * ```
+ */
+export interface CliEnvironment extends AdapterEnvironment {
+    options: CliAdapterOptions;
+    adapter: AbstractCliAdapterInterface;
+}
+//# sourceMappingURL=environment.interface.d.mts.map

package/dist/src/interfaces/environment.interface.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.interface.d.mts","sourceRoot":"","sources":["../../../src/interfaces/environment.interface.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAEtD,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,sCAAsC,CAAA;AAEvF;;;;GAIG;AAEH,MAAM,WAAW,iBAAiB;CAEjC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,cAAe,SAAQ,kBAAkB;IACxD,OAAO,EAAE,iBAAiB,CAAA;IAC1B,OAAO,EAAE,2BAA2B,CAAA;CACrC"}

package/dist/src/interfaces/index.d.mts

@@ -1,3 +1,5 @@
 export * from './command-handler.interface.mjs';
 export * from './commander-execution-context.interface.mjs';
+export * from './abstract-cli-adapter.interface.mjs';
+export * from './environment.interface.mjs';
 //# sourceMappingURL=index.d.mts.map