@navios/commander 0.5.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@navios/commander",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "author": {
     "name": "Oleksandr Hanzha",
     "email": "alex@granted.name"
@@ -30,11 +30,11 @@
     }
   },
   "devDependencies": {
-    "tsx": "^4.20.5",
-    "typescript": "^5.9.2",
-    "zod": "^4.1.8"
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "zod": "^4.1.13"
   },
   "dependencies": {
-    "@navios/di": "^0.4.2"
+    "@navios/di": "^0.6.0"
   }
 }

package/project.json

@@ -38,11 +38,11 @@
     },
     "build": {
       "executor": "nx:run-commands",
-      "inputs": ["projectSources", "{projectRoot}/tsup.config.mts"],
+      "inputs": ["projectSources", "{projectRoot}/tsdown.config.mts"],
       "outputs": ["{projectRoot}/lib"],
       "dependsOn": ["check", "test:ci", "lint"],
       "options": {
-        "command": "tsup",
+        "command": "tsdown",
         "cwd": "packages/commander"
       }
     },

package/src/commander.application.mts

@@ -1,36 +1,94 @@
-import type { ClassTypeWithInstance, InjectionToken } from '@navios/di'
+import type {
+  ClassTypeWithInstance,
+  InjectionToken,
+  NaviosModule,
+} from '@navios/core'
 
-import { Container, inject, Injectable } from '@navios/di'
+import { Container, inject, Injectable } from '@navios/core'
 
-import type { CommandHandler, Module } from './interfaces/index.mjs'
+import type { CommandHandler } from './interfaces/index.mjs'
 
-import { CliParserService, ModuleLoaderService } from './services/index.mjs'
+import { CommanderExecutionContext } from './interfaces/index.mjs'
+import { CliModuleLoaderService, CliParserService } from './services/index.mjs'
+import { CommandExecutionContext } from './tokens/index.mjs'
 
+/**
+ * Configuration options for CommanderApplication.
+ *
+ * @public
+ */
 export interface CommanderApplicationOptions {}
 
+/**
+ * Main application class for managing CLI command execution.
+ *
+ * This class handles module loading, command registration, and command execution.
+ * It provides both programmatic and CLI-based command execution capabilities.
+ *
+ * @example
+ * ```typescript
+ * const app = await CommanderFactory.create(AppModule)
+ * await app.init()
+ * await app.run(process.argv)
+ * ```
+ */
 @Injectable()
 export class CommanderApplication {
-  private moduleLoader = inject(ModuleLoaderService)
+  private moduleLoader = inject(CliModuleLoaderService)
   private cliParser = inject(CliParserService)
   protected container = inject(Container)
 
-  private appModule: ClassTypeWithInstance<Module> | null = null
+  private appModule: ClassTypeWithInstance<NaviosModule> | null = null
   private options: CommanderApplicationOptions = {}
 
+  /**
+   * Indicates whether the application has been initialized.
+   * Set to `true` after `init()` is called successfully.
+   */
   isInitialized = false
 
+  /**
+   * @internal
+   * Sets up the application with the provided module and options.
+   * This is called automatically by CommanderFactory.create().
+   */
   async setup(
-    appModule: ClassTypeWithInstance<Module>,
+    appModule: ClassTypeWithInstance<NaviosModule>,
     options: CommanderApplicationOptions = {},
   ) {
     this.appModule = appModule
     this.options = options
   }
 
+  /**
+   * Gets the dependency injection container used by this application.
+   *
+   * @returns The Container instance
+   *
+   * @example
+   * ```typescript
+   * const container = app.getContainer()
+   * const service = await container.get(MyService)
+   * ```
+   */
   getContainer() {
     return this.container
   }
 
+  /**
+   * Initializes the application by loading all modules and registering commands.
+   *
+   * 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)
+   *
+   * @example
+   * ```typescript
+   * const app = await CommanderFactory.create(AppModule)
+   * await app.init() // Must be called before run() or executeCommand()
+   * ```
+   */
   async init() {
     if (!this.appModule) {
       throw new Error(
@@ -41,6 +99,27 @@ export class CommanderApplication {
     this.isInitialized = true
   }
 
+  /**
+   * 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.
+   *
+   * @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
+   *
+   * @example
+   * ```typescript
+   * await app.executeCommand('greet', {
+   *   name: 'World',
+   *   greeting: 'Hi'
+   * })
+   * ```
+   */
   async executeCommand(commandPath: string, options: any = {}) {
     if (!this.isInitialized) {
       throw new Error(
@@ -63,20 +142,52 @@ export class CommanderApplication {
       validatedOptions = metadata.optionsSchema.parse(options)
     }
 
-    // Get command instance and execute
-    const commandInstance = await this.container.get<CommandHandler>(
-      commandClass as unknown as InjectionToken<CommandHandler>,
+    // Create execution context and provide it to the container
+    const executionContext = new CommanderExecutionContext(
+      metadata,
+      commandPath,
+      validatedOptions,
     )
 
-    if (!commandInstance.execute) {
-      throw new Error(
-        `[Navios Commander] Command ${commandPath} does not implement execute method`,
+    // Generate a unique request ID for this command execution
+    const requestId = `cmd-${Date.now()}-${Math.random().toString(36).substring(7)}`
+
+    // Begin request context and add ExecutionContext
+    const scopeContainer = this.container.beginRequest(requestId)
+    scopeContainer.addInstance(CommandExecutionContext, executionContext)
+
+    try {
+      // Get command instance and execute
+      const commandInstance = await scopeContainer.get<CommandHandler>(
+        commandClass as unknown as InjectionToken<CommandHandler>,
       )
-    }
 
-    await commandInstance.execute(validatedOptions)
+      if (!commandInstance.execute) {
+        throw new Error(
+          `[Navios Commander] Command ${commandPath} does not implement execute method`,
+        )
+      }
+
+      await commandInstance.execute(validatedOptions)
+    } finally {
+      // Clean up request context
+      await scopeContainer.endRequest()
+    }
   }
 
+  /**
+   * Gets all registered commands with their paths and class references.
+   *
+   * @returns An array of objects containing the command path and class
+   *
+   * @example
+   * ```typescript
+   * const commands = app.getAllCommands()
+   * commands.forEach(({ path }) => {
+   *   console.log(`Available: ${path}`)
+   * })
+   * ```
+   */
   getAllCommands() {
     // Use pre-collected command metadata from module loading
     const commandsMap = this.moduleLoader.getAllCommandsWithMetadata()
@@ -96,8 +207,26 @@ export class CommanderApplication {
   }
 
   /**
-   * Runs the CLI application by parsing process.argv and executing the command
-   * @param argv - Command-line arguments (defaults to process.argv)
+   * 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'])
+   * ```
    */
   async run(argv: string[] = process.argv) {
     if (!this.isInitialized) {
@@ -147,12 +276,27 @@ export class CommanderApplication {
     }
   }
 
+  /**
+   * @internal
+   * Disposes of resources used by the application.
+   */
   async dispose() {
     if (this.moduleLoader) {
       this.moduleLoader.dispose()
     }
   }
 
+  /**
+   * 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()
+   * ```
+   */
   async close() {
     await this.dispose()
   }

package/src/commander.factory.mts

@@ -1,15 +1,43 @@
-import type { ClassTypeWithInstance } from '@navios/di'
+import type { ClassTypeWithInstance, NaviosModule } from '@navios/core'
 
-import { Container } from '@navios/di'
+import { Container } from '@navios/core'
 
 import type { CommanderApplicationOptions } from './commander.application.mjs'
-import type { Module } from './interfaces/index.mjs'
 
 import { CommanderApplication } from './commander.application.mjs'
 
+/**
+ * Factory class for creating and configuring CLI applications.
+ *
+ * @example
+ * ```typescript
+ * import { CommanderFactory } from '@navios/commander'
+ * import { AppModule } from './app.module'
+ *
+ * async function bootstrap() {
+ *   const app = await CommanderFactory.create(AppModule)
+ *   await app.init()
+ *   await app.run(process.argv)
+ *   await app.close()
+ * }
+ * ```
+ */
 export class CommanderFactory {
+  /**
+   * Creates a new CommanderApplication instance and configures it 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
+   *
+   * @example
+   * ```typescript
+   * const app = await CommanderFactory.create(AppModule)
+   * await app.init()
+   * ```
+   */
   static async create(
-    appModule: ClassTypeWithInstance<Module>,
+    appModule: ClassTypeWithInstance<NaviosModule>,
     options: CommanderApplicationOptions = {},
   ) {
     const container = new Container()

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

@@ -1,14 +1,49 @@
-import type { ClassType } from '@navios/di'
+import type { ClassType } from '@navios/core'
 
-import { Injectable, InjectableScope, InjectionToken } from '@navios/di'
+import { Injectable, InjectableScope, InjectionToken } from '@navios/core'
 
 import { getCliModuleMetadata } from '../metadata/index.mjs'
 
+/**
+ * Options for the `@CliModule` decorator.
+ *
+ * @public
+ */
 export interface CliModuleOptions {
+  /**
+   * Array or Set of command classes to register in this module.
+   * Commands must be decorated with `@Command`.
+   */
   commands?: ClassType[] | Set<ClassType>
+  /**
+   * Array or Set of other CLI modules to import.
+   * Imported modules' commands will be available in this module.
+   */
   imports?: ClassType[] | Set<ClassType>
 }
 
+/**
+ * Decorator that marks a class as a CLI module.
+ *
+ * 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
+ * @returns A class decorator function
+ *
+ * @example
+ * ```typescript
+ * import { CliModule } from '@navios/commander'
+ * import { GreetCommand } from './greet.command'
+ * import { UserModule } from './user.module'
+ *
+ * @CliModule({
+ *   commands: [GreetCommand],
+ *   imports: [UserModule]
+ * })
+ * export class AppModule {}
+ * ```
+ */
 export function CliModule(
   { commands = [], imports = [] }: CliModuleOptions = {
     commands: [],

package/src/decorators/command.decorator.mts

@@ -1,15 +1,58 @@
-import type { ClassType } from '@navios/di'
+import type { ClassType } from '@navios/core'
 import type { ZodObject } from 'zod'
 
-import { Injectable, InjectableScope, InjectionToken } from '@navios/di'
+import { Injectable, InjectableScope, InjectionToken } from '@navios/core'
 
 import { getCommandMetadata } from '../metadata/index.mjs'
 
+/**
+ * Options for the `@Command` decorator.
+ *
+ * @public
+ */
 export interface CommandOptions {
+  /**
+   * The command path that users will invoke from the CLI.
+   * Can be a single word (e.g., 'greet') or multi-word with colons (e.g., 'user:create', 'db:migrate').
+   */
   path: string
+  /**
+   * Optional Zod schema for validating command options.
+   * If provided, options will be validated and parsed according to this schema.
+   */
   optionsSchema?: ZodObject
 }
 
+/**
+ * Decorator that marks a class as a CLI command.
+ *
+ * The decorated class must implement the `CommandHandler` interface with an `execute` method.
+ * The command will be automatically registered when its module is loaded.
+ *
+ * @param options - Configuration options for the command
+ * @returns A class decorator function
+ *
+ * @example
+ * ```typescript
+ * import { Command, CommandHandler } from '@navios/commander'
+ * import { z } from 'zod'
+ *
+ * const optionsSchema = z.object({
+ *   name: z.string(),
+ *   greeting: z.string().optional().default('Hello')
+ * })
+ *
+ * @Command({
+ *   path: 'greet',
+ *   optionsSchema: optionsSchema
+ * })
+ * export class GreetCommand implements CommandHandler<z.infer<typeof optionsSchema>> {
+ *   async execute(options) {
+ *     console.log(`${options.greeting}, ${options.name}!`)
+ *   }
+ * }
+ * ```
+ */
 export function Command({ path, optionsSchema }: CommandOptions) {
   return function (target: ClassType, context: ClassDecoratorContext) {
     if (context.kind !== 'class') {

package/src/index.mts

@@ -1,7 +1,11 @@
-export * from '@navios/di'
+// Re-export DI types and values that users might need
+export * from '@navios/core'
+
+// Export commander-specific exports
 export * from './commander.application.mjs'
 export * from './commander.factory.mjs'
 export * from './decorators/index.mjs'
 export * from './interfaces/index.mjs'
 export * from './metadata/index.mjs'
 export * from './services/index.mjs'
+export * from './tokens/index.mjs'

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

@@ -1,3 +1,36 @@
+/**
+ * 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.
+ *
+ * @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}!`)
+ *   }
+ * }
+ * ```
+ */
 export interface CommandHandler<TOptions = any> {
+  /**
+   * 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
+   */
   execute(options: TOptions): void | Promise<void>
 }

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

@@ -0,0 +1,64 @@
+import type { CommandMetadata } from '../metadata/command.metadata.mjs'
+
+/**
+ * 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())
+ *   }
+ * }
+ * ```
+ */
+export class CommanderExecutionContext {
+  /**
+   * @internal
+   * Creates a new execution context.
+   */
+  constructor(
+    private readonly command: CommandMetadata,
+    private readonly commandPath: string,
+    private readonly options: any,
+  ) {}
+
+  /**
+   * Gets the command metadata.
+   *
+   * @returns The command metadata including path and options schema
+   */
+  getCommand(): CommandMetadata {
+    return this.command
+  }
+
+  /**
+   * Gets the command path that was invoked.
+   *
+   * @returns The command path (e.g., 'greet', 'user:create')
+   */
+  getCommandPath(): string {
+    return this.commandPath
+  }
+
+  /**
+   * 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 {
+    return this.options
+  }
+}

package/src/interfaces/index.mts

@@ -1,2 +1,2 @@
-export * from './module.interface.mjs'
 export * from './command-handler.interface.mjs'
+export * from './commander-execution-context.interface.mjs'

package/src/metadata/cli-module.metadata.mts

@@ -1,13 +1,39 @@
-import type { ClassType } from '@navios/di'
+import type { ClassType } from '@navios/core'
 
+/**
+ * @internal
+ * Symbol key used to store CLI module metadata on classes.
+ */
 export const CliModuleMetadataKey = Symbol('CliModuleMetadataKey')
 
+/**
+ * Metadata associated with a CLI module.
+ *
+ * @public
+ */
 export 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>
 }
 
+/**
+ * Gets or creates CLI module metadata for a class.
+ *
+ * @internal
+ * @param target - The module class
+ * @param context - The decorator context
+ * @returns The module metadata
+ */
 export function getCliModuleMetadata(
   target: ClassType,
   context: ClassDecoratorContext,
@@ -33,13 +59,22 @@ export function getCliModuleMetadata(
   throw new Error('[Navios Commander] Wrong environment.')
 }
 
-export function extractCliModuleMetadata(
-  target: ClassType,
-): CliModuleMetadata {
+/**
+ * Extracts CLI module metadata from a class.
+ *
+ * @param target - The module class
+ * @returns The module metadata
+ * @throws {Error} If the class is not decorated with @CliModule
+ *
+ * @example
+ * ```typescript
+ * const metadata = extractCliModuleMetadata(AppModule)
+ * console.log(metadata.commands.size) // Number of commands
+ * ```
+ */
+export function extractCliModuleMetadata(target: ClassType): CliModuleMetadata {
   // @ts-expect-error We add a custom metadata key to the target
-  const metadata = target[CliModuleMetadataKey] as
-    | CliModuleMetadata
-    | undefined
+  const metadata = target[CliModuleMetadataKey] as CliModuleMetadata | undefined
   if (!metadata) {
     throw new Error(
       `[Navios Commander] Module metadata not found for ${target.name}. Make sure to use @CliModule decorator.`,
@@ -48,6 +83,12 @@ export function extractCliModuleMetadata(
   return metadata
 }
 
+/**
+ * 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
+ */
 export function hasCliModuleMetadata(target: ClassType): boolean {
   // @ts-expect-error We add a custom metadata key to the target
   return !!target[CliModuleMetadataKey]