@navios/commander 0.5.0

package/src/commander.application.mts

@@ -0,0 +1,159 @@
+import type { ClassTypeWithInstance, InjectionToken } from '@navios/di'
+
+import { Container, inject, Injectable } from '@navios/di'
+
+import type { CommandHandler, Module } from './interfaces/index.mjs'
+
+import { CliParserService, ModuleLoaderService } from './services/index.mjs'
+
+export interface CommanderApplicationOptions {}
+
+@Injectable()
+export class CommanderApplication {
+  private moduleLoader = inject(ModuleLoaderService)
+  private cliParser = inject(CliParserService)
+  protected container = inject(Container)
+
+  private appModule: ClassTypeWithInstance<Module> | null = null
+  private options: CommanderApplicationOptions = {}
+
+  isInitialized = false
+
+  async setup(
+    appModule: ClassTypeWithInstance<Module>,
+    options: CommanderApplicationOptions = {},
+  ) {
+    this.appModule = appModule
+    this.options = options
+  }
+
+  getContainer() {
+    return this.container
+  }
+
+  async init() {
+    if (!this.appModule) {
+      throw new Error(
+        '[Navios Commander] App module is not set. Call setup() first.',
+      )
+    }
+    await this.moduleLoader.loadModules(this.appModule)
+    this.isInitialized = true
+  }
+
+  async executeCommand(commandPath: string, options: any = {}) {
+    if (!this.isInitialized) {
+      throw new Error(
+        '[Navios Commander] Application is not initialized. Call init() first.',
+      )
+    }
+
+    // Use pre-collected command metadata from module loading
+    const commandWithMetadata = this.moduleLoader.getCommandByPath(commandPath)
+
+    if (!commandWithMetadata) {
+      throw new Error(`[Navios Commander] Command not found: ${commandPath}`)
+    }
+
+    const { class: commandClass, metadata } = commandWithMetadata
+
+    // Validate options with zod schema if provided
+    let validatedOptions = options
+    if (metadata.optionsSchema) {
+      validatedOptions = metadata.optionsSchema.parse(options)
+    }
+
+    // Get command instance and execute
+    const commandInstance = await this.container.get<CommandHandler>(
+      commandClass as unknown as InjectionToken<CommandHandler>,
+    )
+
+    if (!commandInstance.execute) {
+      throw new Error(
+        `[Navios Commander] Command ${commandPath} does not implement execute method`,
+      )
+    }
+
+    await commandInstance.execute(validatedOptions)
+  }
+
+  getAllCommands() {
+    // Use pre-collected command metadata from module loading
+    const commandsMap = this.moduleLoader.getAllCommandsWithMetadata()
+    const commandsWithMetadata: Array<{
+      path: string
+      class: ClassTypeWithInstance<any>
+    }> = []
+
+    for (const [, { class: cmd, metadata }] of commandsMap) {
+      commandsWithMetadata.push({
+        path: metadata.path,
+        class: cmd,
+      })
+    }
+
+    return commandsWithMetadata
+  }
+
+  /**
+   * Runs the CLI application by parsing process.argv and executing the command
+   * @param argv - Command-line arguments (defaults to process.argv)
+   */
+  async run(argv: string[] = process.argv) {
+    if (!this.isInitialized) {
+      throw new Error(
+        '[Navios Commander] Application is not initialized. Call init() first.',
+      )
+    }
+
+    try {
+      // First, try to extract the command path to get its schema
+      // We need to do a preliminary parse to find the command
+      const preliminaryParse = this.cliParser.parse(argv)
+      const commandWithMetadata = this.moduleLoader.getCommandByPath(
+        preliminaryParse.command,
+      )
+
+      // Re-parse with schema if available
+      const parsed = commandWithMetadata?.metadata.optionsSchema
+        ? this.cliParser.parse(argv, commandWithMetadata.metadata.optionsSchema)
+        : preliminaryParse
+
+      // Handle special commands
+      if (
+        parsed.command === 'help' ||
+        parsed.options.help ||
+        parsed.options.h
+      ) {
+        const commands = this.getAllCommands()
+        console.log(this.cliParser.formatCommandList(commands))
+        return
+      }
+
+      // Execute the command
+      await this.executeCommand(parsed.command, parsed.options)
+    } catch (error) {
+      if (error instanceof Error) {
+        console.error(`Error: ${error.message}`)
+
+        // Show available commands on error
+        if (error.message.includes('Command not found')) {
+          console.log(
+            '\n' + this.cliParser.formatCommandList(this.getAllCommands()),
+          )
+        }
+      }
+      throw error
+    }
+  }
+
+  async dispose() {
+    if (this.moduleLoader) {
+      this.moduleLoader.dispose()
+    }
+  }
+
+  async close() {
+    await this.dispose()
+  }
+}

package/src/commander.factory.mts

@@ -0,0 +1,20 @@
+import type { ClassTypeWithInstance } from '@navios/di'
+
+import { Container } from '@navios/di'
+
+import type { CommanderApplicationOptions } from './commander.application.mjs'
+import type { Module } from './interfaces/index.mjs'
+
+import { CommanderApplication } from './commander.application.mjs'
+
+export class CommanderFactory {
+  static async create(
+    appModule: ClassTypeWithInstance<Module>,
+    options: CommanderApplicationOptions = {},
+  ) {
+    const container = new Container()
+    const app = await container.get(CommanderApplication)
+    await app.setup(appModule, options)
+    return app
+  }
+}

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

@@ -0,0 +1,39 @@
+import type { ClassType } from '@navios/di'
+
+import { Injectable, InjectableScope, InjectionToken } from '@navios/di'
+
+import { getCliModuleMetadata } from '../metadata/index.mjs'
+
+export interface CliModuleOptions {
+  commands?: ClassType[] | Set<ClassType>
+  imports?: ClassType[] | Set<ClassType>
+}
+
+export function CliModule(
+  { commands = [], imports = [] }: CliModuleOptions = {
+    commands: [],
+    imports: [],
+  },
+) {
+  return (target: ClassType, context: ClassDecoratorContext) => {
+    if (context.kind !== 'class') {
+      throw new Error(
+        '[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)
+    }
+
+    return Injectable({
+      token,
+      scope: InjectableScope.Singleton,
+    })(target, context)
+  }
+}

package/src/decorators/command.decorator.mts

@@ -0,0 +1,29 @@
+import type { ClassType } from '@navios/di'
+import type { ZodObject } from 'zod'
+
+import { Injectable, InjectableScope, InjectionToken } from '@navios/di'
+
+import { getCommandMetadata } from '../metadata/index.mjs'
+
+export interface CommandOptions {
+  path: string
+  optionsSchema?: ZodObject
+}
+
+export function Command({ path, optionsSchema }: CommandOptions) {
+  return function (target: ClassType, context: ClassDecoratorContext) {
+    if (context.kind !== 'class') {
+      throw new Error(
+        '[Navios Commander] @Command decorator can only be used on classes.',
+      )
+    }
+    const token = InjectionToken.create(target)
+    if (context.metadata) {
+      getCommandMetadata(target, context, path, optionsSchema)
+    }
+    return Injectable({
+      token,
+      scope: InjectableScope.Singleton,
+    })(target, context)
+  }
+}

package/src/decorators/index.mts

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

package/src/index.mts

@@ -0,0 +1,7 @@
+export * from '@navios/di'
+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'

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

@@ -0,0 +1,3 @@
+export interface CommandHandler<TOptions = any> {
+  execute(options: TOptions): void | Promise<void>
+}

package/src/interfaces/index.mts

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

package/src/interfaces/module.interface.mts

@@ -0,0 +1,4 @@
+export interface Module {
+  onModuleInit?(): void | Promise<void>
+  onModuleDestroy?(): void | Promise<void>
+}

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

@@ -0,0 +1,54 @@
+import type { ClassType } from '@navios/di'
+
+export const CliModuleMetadataKey = Symbol('CliModuleMetadataKey')
+
+export interface CliModuleMetadata {
+  commands: Set<ClassType>
+  imports: Set<ClassType>
+  customAttributes: Map<string | symbol, any>
+}
+
+export function getCliModuleMetadata(
+  target: ClassType,
+  context: ClassDecoratorContext,
+): CliModuleMetadata {
+  if (context.metadata) {
+    const metadata = context.metadata[CliModuleMetadataKey] as
+      | CliModuleMetadata
+      | undefined
+    if (metadata) {
+      return metadata
+    } else {
+      const newMetadata: CliModuleMetadata = {
+        commands: new Set<ClassType>(),
+        imports: new Set<ClassType>(),
+        customAttributes: new Map<string | symbol, any>(),
+      }
+      context.metadata[CliModuleMetadataKey] = newMetadata
+      // @ts-expect-error We add a custom metadata key to the target
+      target[CliModuleMetadataKey] = newMetadata
+      return newMetadata
+    }
+  }
+  throw new Error('[Navios Commander] Wrong environment.')
+}
+
+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
+  if (!metadata) {
+    throw new Error(
+      `[Navios Commander] Module metadata not found for ${target.name}. Make sure to use @CliModule decorator.`,
+    )
+  }
+  return metadata
+}
+
+export function hasCliModuleMetadata(target: ClassType): boolean {
+  // @ts-expect-error We add a custom metadata key to the target
+  return !!target[CliModuleMetadataKey]
+}

package/src/metadata/command.metadata.mts

@@ -0,0 +1,54 @@
+import type { ClassType } from '@navios/di'
+import type { ZodObject } from 'zod'
+
+export const CommandMetadataKey = Symbol('CommandMetadataKey')
+
+export interface CommandMetadata {
+  path: string
+  optionsSchema?: ZodObject
+  customAttributes: Map<string | symbol, any>
+}
+
+export function getCommandMetadata(
+  target: ClassType,
+  context: ClassDecoratorContext,
+  path: string,
+  optionsSchema?: ZodObject,
+): CommandMetadata {
+  if (context.metadata) {
+    const metadata = context.metadata[CommandMetadataKey] as
+      | CommandMetadata
+      | undefined
+    if (metadata) {
+      return metadata
+    } else {
+      const newMetadata: CommandMetadata = {
+        path,
+        optionsSchema,
+        customAttributes: new Map<string | symbol, any>(),
+      }
+      context.metadata[CommandMetadataKey] = newMetadata
+      // @ts-expect-error We add a custom metadata key to the target
+      target[CommandMetadataKey] = newMetadata
+      return newMetadata
+    }
+  }
+  throw new Error('[Navios Commander] Wrong environment.')
+}
+
+export function extractCommandMetadata(target: ClassType): CommandMetadata {
+  // @ts-expect-error We add a custom metadata key to the target
+  const metadata = target[CommandMetadataKey] as CommandMetadata | undefined
+  if (!metadata) {
+    throw new Error(
+      '[Navios Commander] Command metadata not found. Make sure to use @Command decorator.',
+    )
+  }
+  return metadata
+}
+
+export function hasCommandMetadata(target: ClassType): boolean {
+  // @ts-expect-error We add a custom metadata key to the target
+  const metadata = target[CommandMetadataKey] as CommandMetadata | undefined
+  return !!metadata
+}

package/src/metadata/index.mts

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