@navios/commander 1.0.0-alpha.2 → 1.0.0

package/src/commander.factory.mts

@@ -1,13 +1,78 @@
-import type { ClassTypeWithInstance, NaviosModule } from '@navios/core'
+import type {
+  ClassTypeWithInstance,
+  LogLevel,
+  NaviosApplication,
+  NaviosModule,
+} from '@navios/core'
 
-import { Container } from '@navios/core'
+import { ConsoleLogger, NaviosFactory } from '@navios/core'
 
-import type { CommanderApplicationOptions } from './commander.application.mjs'
+import type { CliEnvironment } from './interfaces/environment.interface.mjs'
 
-import { CommanderApplication } from './commander.application.mjs'
+import { defineCliEnvironment } from './define-environment.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
@@ -17,32 +82,59 @@ 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 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 async create(
-    appModule: ClassTypeWithInstance<NaviosModule>,
-    options: CommanderApplicationOptions = {},
-  ) {
-    const container = new Container()
-    const app = await container.get(CommanderApplication)
-    await app.setup(appModule, options)
+  static async create<TModule extends NaviosModule = NaviosModule>(
+    appModule: ClassTypeWithInstance<TModule>,
+    options: CommanderFactoryOptions = {},
+  ): Promise<NaviosApplication<CliEnvironment>> {
+    const app = await NaviosFactory.create<CliEnvironment>(appModule, {
+      adapter: defineCliEnvironment(),
+      logger: ConsoleLogger.create({
+        logLevels: options.logger?.logLevels,
+        showTimeDiff: options.logger?.showTimeDiff ?? false,
+        showPid: options.logger?.showPid ?? false,
+        showLogLevel: options.logger?.showLogLevel ?? true,
+        showPrefix: options.logger?.showPrefix ?? false,
+        showContext: options.logger?.showContext ?? true,
+        showTimestamp: options.logger?.showTimestamp ?? false,
+      }),
+    })
+
     return app
   }
 }

package/src/commands/help.command.mts

@@ -0,0 +1,37 @@
+import { inject, Logger } from '@navios/core'
+
+import { z } from 'zod'
+
+import type { CommandHandler } from '../interfaces/command-handler.interface.mjs'
+
+import { Command } from '../decorators/command.decorator.mjs'
+import { CommandRegistryService } from '../services/command-registry.service.mjs'
+
+const helpOptionsSchema = z.object({
+  command: z.string().optional(),
+})
+
+type HelpOptions = z.infer<typeof helpOptionsSchema>
+
+/**
+ * Built-in help command that lists all available commands or shows help for a specific command.
+ *
+ * @public
+ */
+@Command({
+  path: 'help',
+  description: 'Show available commands or help for a specific command',
+  optionsSchema: helpOptionsSchema,
+})
+export class HelpCommand implements CommandHandler<HelpOptions> {
+  private logger = inject(Logger, { context: 'Commander' })
+  private commandRegistry = inject(CommandRegistryService)
+
+  async execute(options: HelpOptions): Promise<void> {
+    if (options.command) {
+      this.logger.log(this.commandRegistry.formatCommandHelp(options.command))
+    } else {
+      this.logger.log(this.commandRegistry.formatCommandList())
+    }
+  }
+}

package/src/commands/index.mts

@@ -0,0 +1 @@
+export * from './help.command.mjs'

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

@@ -1,8 +1,11 @@
 import type { ClassType, Registry } from '@navios/core'
 
-import { Injectable, InjectableScope, InjectionToken } from '@navios/core'
+import { Module, getModuleMetadata, getModuleCustomEntry } from '@navios/core'
 
-import { getCliModuleMetadata } from '../metadata/index.mjs'
+import {
+  CommandEntryKey,
+  type CommandEntryValue,
+} from '../metadata/command-entry.metadata.mjs'
 
 /**
  * Options for the `@CliModule` decorator.
@@ -16,10 +19,20 @@ 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,
@@ -42,7 +55,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
@@ -60,17 +77,32 @@ export interface CliModuleOptions {
  * })
  * export class AppModule {}
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Mixed HTTP and CLI module
+ * @CliModule({
+ *   controllers: [HealthController],
+ *   commands: [MigrateCommand],
+ *   imports: [DatabaseModule],
+ * })
+ * export class AppModule {}
+ * ```
  */
 export function CliModule(
   {
     commands = [],
+    controllers = [],
     imports = [],
+    guards = [],
     overrides = [],
     priority,
     registry,
   }: CliModuleOptions = {
     commands: [],
+    controllers: [],
     imports: [],
+    guards: [],
     overrides: [],
   },
 ) {
@@ -80,24 +112,30 @@ export function CliModule(
         '[Navios Commander] @CliModule decorator can only be used on classes.',
       )
     }
-    // Register the module in the service locator
-    const token = InjectionToken.create(target)
-    const moduleMetadata = getCliModuleMetadata(target, context)
-    for (const command of commands) {
-      moduleMetadata.commands.add(command)
-    }
-    for (const importedModule of imports) {
-      moduleMetadata.imports.add(importedModule)
-    }
-    for (const override of overrides) {
-      moduleMetadata.overrides.add(override)
-    }
 
-    return Injectable({
-      token,
-      scope: InjectableScope.Singleton,
+    // Apply standard @Module decorator first
+    const result = Module({
+      controllers,
+      imports,
+      guards,
+      overrides,
       priority,
       registry,
     })(target, context)
+
+    // Get the module metadata that @Module just created
+    const metadata = getModuleMetadata(target, context)
+
+    // Store commands in customEntries
+    const commandSet = getModuleCustomEntry<CommandEntryValue>(
+      metadata,
+      CommandEntryKey,
+      () => new Set(),
+    )
+    for (const command of commands) {
+      commandSet.add(command)
+    }
+
+    return result
   }
 }

package/src/decorators/command.decorator.mts

@@ -16,6 +16,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.
@@ -65,6 +70,7 @@ export interface CommandOptions {
  */
 export function Command({
   path,
+  description,
   optionsSchema,
   priority,
   registry,
@@ -77,7 +83,7 @@ export function Command({
     }
     const token = InjectionToken.create(target)
     if (context.metadata) {
-      getCommandMetadata(target, context, path, optionsSchema)
+      getCommandMetadata(target, context, path, description, optionsSchema)
     }
     return Injectable({
       token,

package/src/define-environment.mts

@@ -0,0 +1,39 @@
+import type { AnyInjectableType, InjectionToken } from '@navios/core'
+
+import { AdapterToken } 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 function defineCliEnvironment() {
+  const tokens = new Map<InjectionToken<any, undefined>, AnyInjectableType>([
+    [AdapterToken, CommanderAdapterService],
+  ])
+  return { tokens }
+}
+
+// Re-export services for direct access if needed
+export { CommanderAdapterService, CommandRegistryService, CliParserService }

package/src/index.mts

@@ -2,9 +2,10 @@
 export * from '@navios/core'
 
 // Export commander-specific exports
-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/src/interfaces/abstract-cli-adapter.interface.mts

@@ -0,0 +1,52 @@
+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 }>
+}

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

@@ -8,7 +8,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/src/interfaces/environment.interface.mts

@@ -0,0 +1,34 @@
+import type { AdapterEnvironment } from '@navios/core'
+
+import type { AbstractCliAdapterInterface } from './abstract-cli-adapter.interface.mjs'
+
+/**
+ * Options for configuring the CLI adapter.
+ *
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface CliAdapterOptions {
+  // Reserved for future options
+}
+
+/**
+ * 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
+}

package/src/interfaces/index.mts

@@ -1,2 +1,4 @@
 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'

package/src/metadata/command-entry.metadata.mts

@@ -0,0 +1,41 @@
+import type { ClassType } from '@navios/core'
+
+import { extractModuleMetadata } from '@navios/core'
+
+/**
+ * Symbol key for storing commands in ModuleMetadata.customEntries.
+ * Used by @CliModule to store command classes.
+ *
+ * @public
+ */
+export const CommandEntryKey = Symbol('CommandEntryKey')
+
+/**
+ * Type for the command entry value stored in customEntries.
+ *
+ * @public
+ */
+export type CommandEntryValue = Set<ClassType>
+
+/**
+ * Extracts commands from a module's metadata.
+ * Returns empty set if no commands are defined.
+ *
+ * @param moduleClass - The module class decorated with @CliModule or @Module
+ * @returns Set of command classes registered in the module
+ *
+ * @example
+ * ```typescript
+ * const commands = extractModuleCommands(AppModule)
+ * for (const command of commands) {
+ *   console.log(command.name)
+ * }
+ * ```
+ */
+export function extractModuleCommands(moduleClass: ClassType): Set<ClassType> {
+  const metadata = extractModuleMetadata(moduleClass)
+  return (
+    (metadata.customEntries.get(CommandEntryKey) as CommandEntryValue) ??
+    new Set()
+  )
+}

package/src/metadata/command.metadata.mts

@@ -17,6 +17,10 @@ export 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.
    */
@@ -34,6 +38,7 @@ export 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
  */
@@ -41,6 +46,7 @@ export function getCommandMetadata(
   target: ClassType,
   context: ClassDecoratorContext,
   path: string,
+  description?: string,
   optionsSchema?: ZodObject,
 ): CommandMetadata {
   if (context.metadata) {
@@ -52,6 +58,7 @@ export function getCommandMetadata(
     } else {
       const newMetadata: CommandMetadata = {
         path,
+        description,
         optionsSchema,
         customAttributes: new Map<string | symbol, any>(),
       }

package/src/metadata/index.mts

@@ -1,2 +1,2 @@
 export * from './command.metadata.mjs'
-export * from './cli-module.metadata.mjs'
+export * from './command-entry.metadata.mjs'

package/src/services/cli-parser.service.mts

@@ -286,20 +286,20 @@ export class CliParserService {
 
   /**
    * Checks if a Zod schema represents a boolean type
-   * Unwraps ZodOptional and ZodDefault
+   * Unwraps ZodOptional and ZodDefault using Zod v4 API
    */
   private isSchemaBoolean(schema: ZodType): boolean {
     try {
       let currentSchema = schema
-      const typeName = currentSchema.def.type
+      let typeName = currentSchema.def.type
 
-      // Unwrap ZodOptional and ZodDefault
-      if (typeName === 'optional' || typeName === 'default') {
-        currentSchema = (currentSchema as any)?._def?.innerType || currentSchema
+      // Unwrap ZodOptional and ZodDefault using Zod v4's def.innerType
+      while (typeName === 'optional' || typeName === 'default') {
+        currentSchema = (currentSchema as any)?.def?.innerType || currentSchema
+        typeName = currentSchema.def.type
       }
 
-      const innerTypeName = currentSchema.def.type
-      return innerTypeName === 'boolean'
+      return typeName === 'boolean'
     } catch {
       return false
     }
@@ -307,36 +307,22 @@ export class CliParserService {
 
   /**
    * Checks if a Zod schema represents an array type
-   * Unwraps ZodOptional and ZodDefault
+   * Unwraps ZodOptional and ZodDefault using Zod v4 API
    */
   private isSchemaArray(schema: ZodType): boolean {
     try {
       let currentSchema = schema
-      const typeName = currentSchema.def.type
+      let typeName = currentSchema.def.type
 
-      // Unwrap ZodOptional and ZodDefault
-      if (typeName === 'optional' || typeName === 'default') {
-        currentSchema = (currentSchema as any)?._def?.innerType || currentSchema
+      // Unwrap ZodOptional and ZodDefault using Zod v4's def.innerType
+      while (typeName === 'optional' || typeName === 'default') {
+        currentSchema = (currentSchema as any)?.def?.innerType || currentSchema
+        typeName = currentSchema.def.type
       }
 
-      const innerTypeName = currentSchema.def.type
-      return innerTypeName === 'array'
+      return typeName === 'array'
     } catch {
       return false
     }
   }
-
-  /**
-   * Formats help text listing all available commands.
-   *
-   * @param commands - Array of command objects with path and class
-   * @returns Formatted string listing all commands
-   */
-  formatCommandList(commands: Array<{ path: string; class: any }>): string {
-    const lines = ['Available commands:', '']
-    for (const { path } of commands) {
-      lines.push(`  ${path}`)
-    }
-    return lines.join('\n')
-  }
 }