@navios/commander 1.5.1 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@navios/commander",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "license": "MIT",
   "author": {
     "name": "Oleksandr Hanzha",
@@ -50,7 +50,7 @@
   },
   "devDependencies": {
     "@navios/builder": "^1.0.0",
-    "@navios/commander-tui": "1.5.1",
+    "@navios/commander-tui": "1.6.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "zod": "^4.3.5"

package/src/__tests__/commander.factory.e2e.spec.mts

@@ -1,9 +1,11 @@
+import { inject } from '@navios/core'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { z } from 'zod/v4'
 
 import { CommanderFactory } from '../commander.factory.mjs'
 import { CliModule } from '../decorators/cli-module.decorator.mjs'
 import { Command } from '../decorators/command.decorator.mjs'
+import { CommandExecutionContext } from '../tokens/index.mjs'
 
 import type { CommandHandler } from '../interfaces/command-handler.interface.mjs'
 
@@ -573,44 +575,134 @@ describe('CommanderApplication E2E - run() with different argv', () => {
 
     @Command({ path: 'copy', optionsSchema })
     class CopyCommand implements CommandHandler<z.infer<typeof optionsSchema>> {
-      async execute(options: z.infer<typeof optionsSchema>) {
-        executeMock(options)
+      async execute(options: z.infer<typeof optionsSchema>, positionals?: string[]) {
+        executeMock(options, positionals)
+      }
+    }
+
+    const noOptionsMock = vi.fn()
+
+    @Command({ path: 'ping' })
+    class PingCommand implements CommandHandler {
+      async execute(_options: unknown, positionals?: string[]) {
+        noOptionsMock(positionals)
       }
     }
 
     @CliModule({
-      commands: [CopyCommand],
+      commands: [CopyCommand, PingCommand],
     })
     class TestModule {}
 
     beforeEach(() => {
       executeMock.mockClear()
+      noOptionsMock.mockClear()
     })
 
-    it('should parse command with options only', async () => {
+    it('should pass empty positionals for command without options', async () => {
       const app = await CommanderFactory.create(TestModule)
       await app.init()
 
       const adapter = app.getAdapter()
-      await adapter.run(['node', 'script.js', 'copy', '--force'])
+      await adapter.run(['node', 'script.js', 'ping'])
 
-      expect(executeMock).toHaveBeenCalledWith({
-        force: true,
-      })
+      expect(noOptionsMock).toHaveBeenCalledWith([])
       await app.close()
     })
 
-    it('should parse command with mixed options and positionals', async () => {
+    it('should parse command with options only and empty positionals', async () => {
       const app = await CommanderFactory.create(TestModule)
       await app.init()
 
       const adapter = app.getAdapter()
-      // Note: positionals are not extracted in this test, but the command should still execute
       await adapter.run(['node', 'script.js', 'copy', '--force'])
 
-      expect(executeMock).toHaveBeenCalledWith({
-        force: true,
-      })
+      expect(executeMock).toHaveBeenCalledWith({ force: true }, [])
+      await app.close()
+    })
+
+    it('should pass positionals as second argument to execute', async () => {
+      const app = await CommanderFactory.create(TestModule)
+      await app.init()
+
+      const adapter = app.getAdapter()
+      // Positionals must come after at least one option because the parser
+      // collects command words until it hits an argument starting with '-'
+      await adapter.run(['node', 'script.js', 'copy', '--force', 'source.txt', 'dest.txt'])
+
+      expect(executeMock).toHaveBeenCalledWith({ force: true }, ['source.txt', 'dest.txt'])
+      await app.close()
+    })
+
+    it('should pass multiple positionals after options', async () => {
+      const app = await CommanderFactory.create(TestModule)
+      await app.init()
+
+      const adapter = app.getAdapter()
+      await adapter.run([
+        'node',
+        'script.js',
+        'copy',
+        '--force',
+        'file1.txt',
+        'file2.txt',
+        'file3.txt',
+      ])
+
+      expect(executeMock).toHaveBeenCalledWith({ force: true }, [
+        'file1.txt',
+        'file2.txt',
+        'file3.txt',
+      ])
+      await app.close()
+    })
+  })
+
+  describe('positionals via execution context', () => {
+    const contextMock = vi.fn()
+
+    const processSchema = z.object({
+      verbose: z.boolean().optional().default(false),
+    })
+
+    @Command({ path: 'process', optionsSchema: processSchema })
+    class ProcessCommand implements CommandHandler<z.infer<typeof processSchema>> {
+      private ctx = inject(CommandExecutionContext)
+
+      async execute() {
+        contextMock(this.ctx.getPositionals())
+      }
+    }
+
+    @CliModule({
+      commands: [ProcessCommand],
+    })
+    class ContextTestModule {}
+
+    beforeEach(() => {
+      contextMock.mockClear()
+    })
+
+    it('should access positionals via CommandExecutionContext', async () => {
+      const app = await CommanderFactory.create(ContextTestModule)
+      await app.init()
+
+      const adapter = app.getAdapter()
+      // Positionals must come after at least one option
+      await adapter.run(['node', 'script.js', 'process', '--verbose', 'file1.txt', 'file2.txt'])
+
+      expect(contextMock).toHaveBeenCalledWith(['file1.txt', 'file2.txt'])
+      await app.close()
+    })
+
+    it('should return empty array when no positionals via context', async () => {
+      const app = await CommanderFactory.create(ContextTestModule)
+      await app.init()
+
+      const adapter = app.getAdapter()
+      await adapter.run(['node', 'script.js', 'process', '--verbose'])
+
+      expect(contextMock).toHaveBeenCalledWith([])
       await app.close()
     })
   })

package/src/interfaces/command-handler.interface.mts

@@ -19,18 +19,22 @@
  *
  * @Command({ path: 'greet', optionsSchema })
  * export class GreetCommand implements CommandHandler<Options> {
- *   async execute(options: Options) {
+ *   async execute(options: Options, positionals?: string[]) {
  *     console.log(`Hello, ${options.name}!`)
+ *     if (positionals?.length) {
+ *       console.log(`Files: ${positionals.join(', ')}`)
+ *     }
  *   }
  * }
  * ```
  */
 export interface CommandHandler<TOptions = any> {
   /**
-   * Executes the command with the provided options.
+   * Executes the command with the provided options and positional arguments.
    *
    * @param options - The validated command options (validated against the command's schema if provided)
+   * @param positionals - Positional arguments that don't match any option flags
    * @returns A promise or void
    */
-  execute(options: TOptions): void | Promise<void>
+  execute(options: TOptions, positionals?: string[]): void | Promise<void>
 }

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

@@ -31,6 +31,7 @@ export class CommanderExecutionContext {
     private readonly command: CommandMetadata,
     private readonly commandPath: string,
     private readonly options: any,
+    private readonly positionals: string[] = [],
   ) {}
 
   /**
@@ -61,4 +62,16 @@ export class CommanderExecutionContext {
   getOptions(): any {
     return this.options
   }
+
+  /**
+   * Gets the positional arguments.
+   *
+   * Positional arguments are values that don't match any option flags.
+   * For example, in `copy --force source.txt dest.txt`, the positionals are `['source.txt', 'dest.txt']`.
+   *
+   * @returns The positional arguments array
+   */
+  getPositionals(): string[] {
+    return this.positionals
+  }
 }

package/src/services/commander-adapter.service.mts

@@ -130,7 +130,7 @@ export class CommanderAdapterService implements AbstractCliAdapterInterface {
         ? this.cliParser.parse(argv, command.metadata.optionsSchema)
         : preliminaryParse
 
-      await this.executeCommand(parsed.command, parsed.options)
+      await this.executeCommand(parsed.command, parsed.options, parsed.positionals)
     } catch (error) {
       if (error instanceof Error) {
         this.logger.error(`Error: ${error.message}`)
@@ -146,7 +146,11 @@ export class CommanderAdapterService implements AbstractCliAdapterInterface {
   /**
    * Execute a command programmatically with the provided options.
    */
-  async executeCommand(path: string, options: Record<string, unknown> = {}): Promise<void> {
+  async executeCommand(
+    path: string,
+    options: Record<string, unknown> = {},
+    positionals: string[] = [],
+  ): Promise<void> {
     const command = this.commandRegistry.getByPath(path)
     if (!command) {
       throw new Error(`[Navios Commander] Command not found: ${path}`)
@@ -161,7 +165,12 @@ export class CommanderAdapterService implements AbstractCliAdapterInterface {
     }
 
     // Create execution context
-    const executionContext = new CommanderExecutionContext(metadata, path, validatedOptions)
+    const executionContext = new CommanderExecutionContext(
+      metadata,
+      path,
+      validatedOptions,
+      positionals,
+    )
 
     // Begin request scope
     const requestId = `cmd-${Date.now()}-${Math.random().toString(36).substring(7)}`
@@ -177,7 +186,7 @@ export class CommanderAdapterService implements AbstractCliAdapterInterface {
         throw new Error(`Command ${path} does not implement execute method`)
       }
 
-      await commandInstance.execute(validatedOptions)
+      await commandInstance.execute(validatedOptions, positionals)
     } finally {
       await scopeContainer.endRequest()
     }

package/lib/cli-module.decorator-BzsOEMPH.d.cts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli-module.decorator-BzsOEMPH.d.cts","names":["CommandHandler","TOptions","Promise","InjectionToken","ClassType","ClassTypeWithInstance","Registry","z","CommandHandler","CommandOptions","ZodObject","Command","path","description","token","optionsSchema","priority","registry","ClassDecoratorContext","ClassType","Registry","CliModuleOptions","Set","CliModule","commands","controllers","imports","guards","overrides","priority","registry","ClassDecoratorContext"],"sources":["../src/interfaces/command-handler.interface.d.mts","../src/decorators/command.decorator.d.mts","../src/decorators/cli-module.decorator.d.mts"],"sourcesContent":["/**\n * Interface that all command classes must implement.\n *\n * Commands decorated with `@Command` must implement this interface.\n * The `execute` method is called when the command is invoked.\n *\n * @template TOptions - The type of options that the command accepts\n *\n * @example\n * ```typescript\n * import { Command, CommandHandler } from '@navios/commander'\n * import { z } from 'zod/v4'\n *\n * const optionsSchema = z.object({\n *   name: z.string()\n * })\n *\n * type Options = z.infer<typeof optionsSchema>\n *\n * @Command({ path: 'greet', optionsSchema })\n * export class GreetCommand implements CommandHandler<Options> {\n *   async execute(options: Options) {\n *     console.log(`Hello, ${options.name}!`)\n *   }\n * }\n * ```\n */\nexport interface CommandHandler<TOptions = any> {\n  /**\n   * Executes the command with the provided options.\n   *\n   * @param options - The validated command options (validated against the command's schema if provided)\n   * @returns A promise or void\n   */\n  execute(options: TOptions): void | Promise<void>\n}\n//# sourceMappingURL=command-handler.interface.d.mts.map\n","import { InjectionToken } from '@navios/core'\n\nimport type { ClassType, ClassTypeWithInstance, Registry } from '@navios/core'\nimport type { z } from 'zod/v4'\n\nimport type { CommandHandler } from '../interfaces/index.mjs'\n/**\n * Options for the `@Command` decorator.\n *\n * @public\n */\nexport interface CommandOptions {\n  /**\n   * The token to use for the command.\n   * If provided, the command will be registered with this token.\n   */\n  token?: InjectionToken<ClassTypeWithInstance<CommandHandler<any>>>\n  /**\n   * The command path that users will invoke from the CLI.\n   * Can be a single word (e.g., 'greet') or multi-word with colons (e.g., 'user:create', 'db:migrate').\n   */\n  path: string\n  /**\n   * Optional description of the command for help text.\n   * Displayed when users run `help` or `--help`.\n   */\n  description?: string\n  /**\n   * Optional zod/v4 schema for validating command options.\n   * If provided, options will be validated and parsed according to this schema.\n   */\n  optionsSchema?: z.ZodObject\n  /**\n   * Priority level for the command.\n   * Higher priority commands will be loaded first.\n   */\n  priority?: number\n  /**\n   * Registry to use for the command.\n   * Registry is used to store the command and its options schema.\n   */\n  registry?: Registry\n}\n/**\n * Decorator that marks a class as a CLI command.\n *\n * The decorated class must implement the `CommandHandler` interface with an `execute` method.\n * The command will be automatically registered when its module is loaded.\n *\n * @param options - Configuration options for the command\n * @returns A class decorator function\n *\n * @example\n * ```typescript\n * import { Command, CommandHandler } from '@navios/commander'\n * import { z } from 'zod/v4'\n *\n * const optionsSchema = z.object({\n *   name: z.string(),\n *   greeting: z.string().optional().default('Hello')\n * })\n *\n * @Command({\n *   path: 'greet',\n *   optionsSchema: optionsSchema\n * })\n * export class GreetCommand implements CommandHandler<z.infer<typeof optionsSchema>> {\n *   async execute(options) {\n *     console.log(`${options.greeting}, ${options.name}!`)\n *   }\n * }\n * ```\n */\nexport declare function Command({\n  path,\n  description,\n  token,\n  optionsSchema,\n  priority,\n  registry,\n}: CommandOptions): (\n  target: ClassType,\n  context: ClassDecoratorContext<abstract new (...args: any) => any>,\n) => any\n//# sourceMappingURL=command.decorator.d.mts.map\n","import type { ClassType, Registry } from '@navios/core'\n/**\n * Options for the `@CliModule` decorator.\n *\n * @public\n */\nexport interface CliModuleOptions {\n  /**\n   * Array or Set of command classes to register in this module.\n   * Commands must be decorated with `@Command`.\n   */\n  commands?: ClassType[] | Set<ClassType>\n  /**\n   * Array or Set of controller classes for HTTP endpoints.\n   * Allows mixing HTTP and CLI functionality in the same module.\n   */\n  controllers?: ClassType[] | Set<ClassType>\n  /**\n   * Array or Set of other modules to import.\n   * Imported modules' commands and controllers will be available.\n   */\n  imports?: ClassType[] | Set<ClassType>\n  /**\n   * Guards to apply to all controllers in this module.\n   * Guards are executed in reverse order (last guard first).\n   */\n  guards?: ClassType[] | Set<ClassType>\n  /**\n   * Service override classes to import for side effects.\n   * These classes are imported to ensure their @Injectable decorators execute,\n   * allowing them to register with the DI system. Overrides should use the same\n   * InjectionToken as the original service with a higher priority.\n   */\n  overrides?: ClassType[] | Set<ClassType>\n  /**\n   * Priority level for the module.\n   * Higher priority modules will be loaded first.\n   */\n  priority?: number\n  /**\n   * Registry to use for the module.\n   * Registry is used to store the module and its commands.\n   */\n  registry?: Registry\n}\n/**\n * Decorator that marks a class as a CLI module.\n *\n * This decorator extends the standard @Module decorator, adding support for\n * CLI commands while maintaining full compatibility with HTTP controllers.\n * Modules organize commands and can import other modules to compose larger\n * CLI applications.\n *\n * The module can optionally implement `NaviosModule` interface for lifecycle hooks.\n *\n * @param options - Configuration options for the module\n * @returns A class decorator function\n *\n * @example\n * ```typescript\n * import { CliModule } from '@navios/commander'\n * import { GreetCommand } from './greet.command'\n * import { UserModule } from './user.module'\n *\n * @CliModule({\n *   commands: [GreetCommand],\n *   imports: [UserModule]\n * })\n * export class AppModule {}\n * ```\n *\n * @example\n * ```typescript\n * // Mixed HTTP and CLI module\n * @CliModule({\n *   controllers: [HealthController],\n *   commands: [MigrateCommand],\n *   imports: [DatabaseModule],\n * })\n * export class AppModule {}\n * ```\n */\nexport declare function CliModule({\n  commands,\n  controllers,\n  imports,\n  guards,\n  overrides,\n  priority,\n  registry,\n}?: CliModuleOptions): (\n  target: ClassType,\n  context: ClassDecoratorContext<abstract new (...args: any) => any>,\n) => ClassType\n//# sourceMappingURL=cli-module.decorator.d.mts.map\n"],"mappings":";;;;;;;;;AA2BA;;;;AChBA;;;;;;;AA8DA;;;;;;;;;;;;UD9CiBA;;AErBjB;;;;;EAUkCmB,OAAAA,CAAAA,OAAAA,EFkBflB,QElBekB,CAAAA,EAAAA,IAAAA,GFkBGjB,OElBHiB,CAAAA,IAAAA,CAAAA;;;;;;ADLlC;;;AAKUhB,UALOM,cAAAA,CAKPN;EAeQI;;;AA0ClB;EACEK,KAAAA,CAAAA,EA1DQT,cA0DRS,CA1DuBP,qBA0DvBO,CA1D6CJ,cA0D7CI,CAAAA,GAAAA,CAAAA,CAAAA,CAAAA;EACAC;;;;EAIAI,IAAAA,EAAAA,MAAAA;EACCR;;;;;;;AC1EH;;EAK+BU,aAAAA,CAAAA,EDoBbZ,CAAAA,CAAEG,SCpBWS;EAAJG;;;;EAUfH,QAAAA,CAAAA,EAAAA,MAAAA;EAAkBA;;;;EAKLG,QAAAA,CAAAA,EDeZhB,QCfYgB;;;;;;AAwDzB;;;;;;;;;;;;;;;;;;;;;;;;;;iBDTwBX,OAAAA;;;;;;;GAOrBF,0BACOL,oBACCc;;;;;;ADvDX;;UErBiBG,gBAAAA;;ADKjB;;;EAKUlB,QAAAA,CAAAA,ECLGgB,SDKHhB,EAAAA,GCLiBmB,GDKjBnB,CCLqBgB,SDKrBhB,CAAAA;EAeQI;;;AA0ClB;EACEK,WAAAA,CAAAA,EC1DcO,SD0DdP,EAAAA,GC1D4BU,GD0D5BV,CC1DgCO,SD0DhCP,CAAAA;EACAC;;;;EAIAI,OAAAA,CAAAA,EC1DUE,SD0DVF,EAAAA,GC1DwBK,GD0DxBL,CC1D4BE,SD0D5BF,CAAAA;EACCR;;;;WCtDQU,cAAcG,IAAIH;;;AApB7B;;;;EAUgBA,SAAAA,CAAAA,EAiBFA,SAjBEA,EAAAA,GAiBYG,GAjBZH,CAiBgBA,SAjBhBA,CAAAA;EAAkBA;;;;EAKRG,QAAAA,CAAAA,EAAAA,MAAAA;EAKfH;;;;EAOqBA,QAAAA,CAAAA,EAUnBC,QAVmBD;;;;AAiDhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAwBI,SAAAA;;;;;;;;IAQpBF,4BACMF,oBACCY,8DACNZ"}

package/lib/cli-module.decorator-CCV_elPP.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli-module.decorator-CCV_elPP.d.mts","names":["CommandHandler","TOptions","Promise","AbstractAdapterInterface","AbstractCliAdapterInterface","Promise","Record","Array","AdapterEnvironment","AbstractCliAdapterInterface","CliAdapterOptions","CliEnvironment","ClassType","z","CommandMetadataKey","CommandMetadata","ZodObject","Map","getCommandMetadata","ClassDecoratorContext","extractCommandMetadata","hasCommandMetadata","CommandMetadata","CommanderExecutionContext","InjectionToken","ClassType","ClassTypeWithInstance","Registry","z","CommandHandler","CommandOptions","ZodObject","Command","path","description","token","optionsSchema","priority","registry","ClassDecoratorContext","ClassType","Registry","CliModuleOptions","Set","CliModule","commands","controllers","imports","guards","overrides","priority","registry","ClassDecoratorContext"],"sources":["../src/interfaces/command-handler.interface.d.mts","../src/interfaces/abstract-cli-adapter.interface.d.mts","../src/interfaces/environment.interface.d.mts","../src/metadata/command.metadata.d.mts","../src/interfaces/commander-execution-context.interface.d.mts","../src/decorators/command.decorator.d.mts","../src/decorators/cli-module.decorator.d.mts"],"sourcesContent":["/**\n * Interface that all command classes must implement.\n *\n * Commands decorated with `@Command` must implement this interface.\n * The `execute` method is called when the command is invoked.\n *\n * @template TOptions - The type of options that the command accepts\n *\n * @example\n * ```typescript\n * import { Command, CommandHandler } from '@navios/commander'\n * import { z } from 'zod/v4'\n *\n * const optionsSchema = z.object({\n *   name: z.string()\n * })\n *\n * type Options = z.infer<typeof optionsSchema>\n *\n * @Command({ path: 'greet', optionsSchema })\n * export class GreetCommand implements CommandHandler<Options> {\n *   async execute(options: Options) {\n *     console.log(`Hello, ${options.name}!`)\n *   }\n * }\n * ```\n */\nexport interface CommandHandler<TOptions = any> {\n  /**\n   * Executes the command with the provided options.\n   *\n   * @param options - The validated command options (validated against the command's schema if provided)\n   * @returns A promise or void\n   */\n  execute(options: TOptions): void | Promise<void>\n}\n//# sourceMappingURL=command-handler.interface.d.mts.map\n","import type { AbstractAdapterInterface } from '@navios/core'\n/**\n * Interface for CLI adapters.\n * Extends the base adapter interface with CLI-specific methods.\n *\n * @public\n */\nexport interface AbstractCliAdapterInterface extends AbstractAdapterInterface {\n  /**\n   * Run the CLI application with the given arguments.\n   * Parses arguments and executes the matching command.\n   *\n   * @param argv - Command-line arguments array (defaults to `process.argv`)\n   *\n   * @example\n   * ```typescript\n   * const adapter = app.getAdapter() as AbstractCliAdapterInterface\n   * await adapter.run(process.argv)\n   * ```\n   */\n  run(argv?: string[]): Promise<void>\n  /**\n   * Execute a command programmatically with the provided options.\n   *\n   * @param path - The command path (e.g., 'greet', 'user:create')\n   * @param options - The command options object\n   *\n   * @example\n   * ```typescript\n   * await adapter.executeCommand('user:create', {\n   *   name: 'John',\n   *   email: 'john@example.com',\n   * })\n   * ```\n   */\n  executeCommand(path: string, options: Record<string, unknown>): Promise<void>\n  /**\n   * Get all registered command paths and their class references.\n   *\n   * @returns Array of objects containing path and class\n   *\n   * @example\n   * ```typescript\n   * const commands = adapter.getAllCommands()\n   * commands.forEach(({ path }) => console.log(path))\n   * ```\n   */\n  getAllCommands(): Array<{\n    path: string\n    class: unknown\n  }>\n}\n//# sourceMappingURL=abstract-cli-adapter.interface.d.mts.map\n","import type { AdapterEnvironment } from '@navios/core'\n\nimport type { AbstractCliAdapterInterface } from './abstract-cli-adapter.interface.mjs'\n/**\n * Options for configuring the CLI adapter.\n *\n * @public\n */\nexport interface CliAdapterOptions {}\n/**\n * Environment type definition for CLI adapters.\n * Used with NaviosFactory.create<CliEnvironment>() for type-safe CLI applications.\n *\n * @public\n *\n * @example\n * ```typescript\n * import { NaviosFactory } from '@navios/core'\n * import { defineCliEnvironment, type CliEnvironment } from '@navios/commander'\n *\n * const app = await NaviosFactory.create<CliEnvironment>(AppModule, {\n *   adapter: defineCliEnvironment(),\n * })\n * ```\n */\nexport interface CliEnvironment extends AdapterEnvironment {\n  options: CliAdapterOptions\n  adapter: AbstractCliAdapterInterface\n}\n//# sourceMappingURL=environment.interface.d.mts.map\n","import type { ClassType } from '@navios/core'\nimport type { z } from 'zod/v4'\n/**\n * @internal\n * Symbol key used to store command metadata on classes.\n */\nexport declare const CommandMetadataKey: unique symbol\n/**\n * Metadata associated with a command.\n *\n * @public\n */\nexport interface CommandMetadata {\n  /**\n   * The command path (e.g., 'greet', 'user:create').\n   */\n  path: string\n  /**\n   * Optional description of the command for help text.\n   */\n  description?: string\n  /**\n   * Optional zod/v4 schema for validating command options.\n   */\n  optionsSchema?: z.ZodObject\n  /**\n   * Map of custom attributes that can be attached to the command.\n   */\n  customAttributes: Map<string | symbol, any>\n}\n/**\n * Gets or creates command metadata for a class.\n *\n * @internal\n * @param target - The command class\n * @param context - The decorator context\n * @param path - The command path\n * @param description - Optional description for help text\n * @param optionsSchema - Optional zod/v4 schema\n * @returns The command metadata\n */\nexport declare function getCommandMetadata(\n  target: ClassType,\n  context: ClassDecoratorContext,\n  path: string,\n  description?: string,\n  optionsSchema?: z.ZodObject,\n): CommandMetadata\n/**\n * Extracts command metadata from a class.\n *\n * @param target - The command class\n * @returns The command metadata\n * @throws {Error} If the class is not decorated with @Command\n *\n * @example\n * ```typescript\n * const metadata = extractCommandMetadata(GreetCommand)\n * console.log(metadata.path) // 'greet'\n * ```\n */\nexport declare function extractCommandMetadata(target: ClassType): CommandMetadata\n/**\n * Checks if a class has command metadata.\n *\n * @param target - The class to check\n * @returns `true` if the class is decorated with @Command, `false` otherwise\n */\nexport declare function hasCommandMetadata(target: ClassType): boolean\n//# sourceMappingURL=command.metadata.d.mts.map\n","import type { CommandMetadata } from '../metadata/command.metadata.mjs'\n/**\n * Execution context for a command execution.\n *\n * Provides access to command metadata, path, and validated options during command execution.\n * This context is automatically injected and available via the `CommandExecutionContext` token.\n *\n * @example\n * ```typescript\n * import { inject, Injectable } from '@navios/core'\n * import { CommandExecutionContext } from '@navios/commander'\n *\n * @Injectable()\n * class CommandLogger {\n *   private ctx = inject(CommandExecutionContext)\n *\n *   log() {\n *     console.log('Command:', this.ctx.getCommandPath())\n *     console.log('Options:', this.ctx.getOptions())\n *   }\n * }\n * ```\n */\nexport declare class CommanderExecutionContext {\n  private readonly command\n  private readonly commandPath\n  private readonly options\n  /**\n   * @internal\n   * Creates a new execution context.\n   */\n  constructor(command: CommandMetadata, commandPath: string, options: any)\n  /**\n   * Gets the command metadata.\n   *\n   * @returns The command metadata including path and options schema\n   */\n  getCommand(): CommandMetadata\n  /**\n   * Gets the command path that was invoked.\n   *\n   * @returns The command path (e.g., 'greet', 'user:create')\n   */\n  getCommandPath(): string\n  /**\n   * Gets the validated command options.\n   *\n   * Options are validated against the command's zod/v4 schema if one was provided.\n   *\n   * @returns The validated options object\n   */\n  getOptions(): any\n}\n//# sourceMappingURL=commander-execution-context.interface.d.mts.map\n","import { InjectionToken } from '@navios/core'\n\nimport type { ClassType, ClassTypeWithInstance, Registry } from '@navios/core'\nimport type { z } from 'zod/v4'\n\nimport type { CommandHandler } from '../interfaces/index.mjs'\n/**\n * Options for the `@Command` decorator.\n *\n * @public\n */\nexport interface CommandOptions {\n  /**\n   * The token to use for the command.\n   * If provided, the command will be registered with this token.\n   */\n  token?: InjectionToken<ClassTypeWithInstance<CommandHandler<any>>>\n  /**\n   * The command path that users will invoke from the CLI.\n   * Can be a single word (e.g., 'greet') or multi-word with colons (e.g., 'user:create', 'db:migrate').\n   */\n  path: string\n  /**\n   * Optional description of the command for help text.\n   * Displayed when users run `help` or `--help`.\n   */\n  description?: string\n  /**\n   * Optional zod/v4 schema for validating command options.\n   * If provided, options will be validated and parsed according to this schema.\n   */\n  optionsSchema?: z.ZodObject\n  /**\n   * Priority level for the command.\n   * Higher priority commands will be loaded first.\n   */\n  priority?: number\n  /**\n   * Registry to use for the command.\n   * Registry is used to store the command and its options schema.\n   */\n  registry?: Registry\n}\n/**\n * Decorator that marks a class as a CLI command.\n *\n * The decorated class must implement the `CommandHandler` interface with an `execute` method.\n * The command will be automatically registered when its module is loaded.\n *\n * @param options - Configuration options for the command\n * @returns A class decorator function\n *\n * @example\n * ```typescript\n * import { Command, CommandHandler } from '@navios/commander'\n * import { z } from 'zod/v4'\n *\n * const optionsSchema = z.object({\n *   name: z.string(),\n *   greeting: z.string().optional().default('Hello')\n * })\n *\n * @Command({\n *   path: 'greet',\n *   optionsSchema: optionsSchema\n * })\n * export class GreetCommand implements CommandHandler<z.infer<typeof optionsSchema>> {\n *   async execute(options) {\n *     console.log(`${options.greeting}, ${options.name}!`)\n *   }\n * }\n * ```\n */\nexport declare function Command({\n  path,\n  description,\n  token,\n  optionsSchema,\n  priority,\n  registry,\n}: CommandOptions): (\n  target: ClassType,\n  context: ClassDecoratorContext<abstract new (...args: any) => any>,\n) => any\n//# sourceMappingURL=command.decorator.d.mts.map\n","import type { ClassType, Registry } from '@navios/core'\n/**\n * Options for the `@CliModule` decorator.\n *\n * @public\n */\nexport interface CliModuleOptions {\n  /**\n   * Array or Set of command classes to register in this module.\n   * Commands must be decorated with `@Command`.\n   */\n  commands?: ClassType[] | Set<ClassType>\n  /**\n   * Array or Set of controller classes for HTTP endpoints.\n   * Allows mixing HTTP and CLI functionality in the same module.\n   */\n  controllers?: ClassType[] | Set<ClassType>\n  /**\n   * Array or Set of other modules to import.\n   * Imported modules' commands and controllers will be available.\n   */\n  imports?: ClassType[] | Set<ClassType>\n  /**\n   * Guards to apply to all controllers in this module.\n   * Guards are executed in reverse order (last guard first).\n   */\n  guards?: ClassType[] | Set<ClassType>\n  /**\n   * Service override classes to import for side effects.\n   * These classes are imported to ensure their @Injectable decorators execute,\n   * allowing them to register with the DI system. Overrides should use the same\n   * InjectionToken as the original service with a higher priority.\n   */\n  overrides?: ClassType[] | Set<ClassType>\n  /**\n   * Priority level for the module.\n   * Higher priority modules will be loaded first.\n   */\n  priority?: number\n  /**\n   * Registry to use for the module.\n   * Registry is used to store the module and its commands.\n   */\n  registry?: Registry\n}\n/**\n * Decorator that marks a class as a CLI module.\n *\n * This decorator extends the standard @Module decorator, adding support for\n * CLI commands while maintaining full compatibility with HTTP controllers.\n * Modules organize commands and can import other modules to compose larger\n * CLI applications.\n *\n * The module can optionally implement `NaviosModule` interface for lifecycle hooks.\n *\n * @param options - Configuration options for the module\n * @returns A class decorator function\n *\n * @example\n * ```typescript\n * import { CliModule } from '@navios/commander'\n * import { GreetCommand } from './greet.command'\n * import { UserModule } from './user.module'\n *\n * @CliModule({\n *   commands: [GreetCommand],\n *   imports: [UserModule]\n * })\n * export class AppModule {}\n * ```\n *\n * @example\n * ```typescript\n * // Mixed HTTP and CLI module\n * @CliModule({\n *   controllers: [HealthController],\n *   commands: [MigrateCommand],\n *   imports: [DatabaseModule],\n * })\n * export class AppModule {}\n * ```\n */\nexport declare function CliModule({\n  commands,\n  controllers,\n  imports,\n  guards,\n  overrides,\n  priority,\n  registry,\n}?: CliModuleOptions): (\n  target: ClassType,\n  context: ClassDecoratorContext<abstract new (...args: any) => any>,\n) => ClassType\n//# sourceMappingURL=cli-module.decorator.d.mts.map\n"],"mappings":"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"}