@navios/commander 0.5.1 → 0.7.0

package/src/metadata/command.metadata.mts

@@ -1,14 +1,42 @@
-import type { ClassType } from '@navios/di'
+import type { ClassType } from '@navios/core'
 import type { ZodObject } from 'zod'
 
+/**
+ * @internal
+ * Symbol key used to store command metadata on classes.
+ */
 export const CommandMetadataKey = Symbol('CommandMetadataKey')
 
+/**
+ * Metadata associated with a command.
+ *
+ * @public
+ */
 export interface CommandMetadata {
+  /**
+   * The command path (e.g., 'greet', 'user:create').
+   */
   path: string
+  /**
+   * Optional Zod schema for validating command options.
+   */
   optionsSchema?: ZodObject
+  /**
+   * Map of custom attributes that can be attached to the command.
+   */
   customAttributes: Map<string | symbol, any>
 }
 
+/**
+ * Gets or creates command metadata for a class.
+ *
+ * @internal
+ * @param target - The command class
+ * @param context - The decorator context
+ * @param path - The command path
+ * @param optionsSchema - Optional Zod schema
+ * @returns The command metadata
+ */
 export function getCommandMetadata(
   target: ClassType,
   context: ClassDecoratorContext,
@@ -36,6 +64,19 @@ export function getCommandMetadata(
   throw new Error('[Navios Commander] Wrong environment.')
 }
 
+/**
+ * Extracts command metadata from a class.
+ *
+ * @param target - The command class
+ * @returns The command metadata
+ * @throws {Error} If the class is not decorated with @Command
+ *
+ * @example
+ * ```typescript
+ * const metadata = extractCommandMetadata(GreetCommand)
+ * console.log(metadata.path) // 'greet'
+ * ```
+ */
 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
@@ -47,6 +88,12 @@ export function extractCommandMetadata(target: ClassType): CommandMetadata {
   return metadata
 }
 
+/**
+ * Checks if a class has command metadata.
+ *
+ * @param target - The class to check
+ * @returns `true` if the class is decorated with @Command, `false` otherwise
+ */
 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

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

@@ -1,4 +1,4 @@
-import { Container } from '@navios/di'
+import { Container } from '@navios/core'
 
 import { beforeEach, describe, expect, it } from 'vitest'
 import { z } from 'zod'
@@ -434,14 +434,7 @@ describe('CliParserService', () => {
       })
 
       const result = parser.parse(
-        [
-          'node',
-          'script.js',
-          'test',
-          '--tags=foo',
-          '--tags=bar',
-          '--tags=baz',
-        ],
+        ['node', 'script.js', 'test', '--tags=foo', '--tags=bar', '--tags=baz'],
         schema,
       )
 
@@ -600,12 +593,23 @@ describe('CliParserService', () => {
       })
 
       const result = parser.parse(
-        ['node', 'script.js', 'test', '--items', '[1,2,3]', '--items', '["a","b"]'],
+        [
+          'node',
+          'script.js',
+          'test',
+          '--items',
+          '[1,2,3]',
+          '--items',
+          '["a","b"]',
+        ],
         schema,
       )
 
       expect(result.options).toEqual({
-        items: [[1, 2, 3], ['a', 'b']],
+        items: [
+          [1, 2, 3],
+          ['a', 'b'],
+        ],
       })
     })
 

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

@@ -1,13 +1,41 @@
 import type { ZodObject, ZodType } from 'zod'
 
-import { Injectable } from '@navios/di'
+import { Injectable } from '@navios/core'
 
+/**
+ * Result of parsing command-line arguments.
+ *
+ * @public
+ */
 export interface ParsedCliArgs {
+  /**
+   * The command path (e.g., 'greet', 'user:create').
+   * Multi-word commands are joined with spaces.
+   */
   command: string
+  /**
+   * Parsed options as key-value pairs.
+   * Keys are converted from kebab-case to camelCase.
+   */
   options: Record<string, any>
+  /**
+   * Positional arguments that don't match any option flags.
+   */
   positionals: string[]
 }
 
+/**
+ * Service for parsing command-line arguments.
+ *
+ * Handles parsing of various CLI argument formats including:
+ * - Long options: `--key value` or `--key=value`
+ * - Short options: `-k value` or `-abc` (multiple flags)
+ * - Boolean flags
+ * - Array options
+ * - Positional arguments
+ *
+ * @public
+ */
 @Injectable()
 export class CliParserService {
   /**
@@ -63,7 +91,8 @@ export class CliParserService {
           const optionName = key.slice(0, equalIndex)
           const optionValue = key.slice(equalIndex + 1)
           const camelCaseKey = this.camelCase(optionName)
-          const isArray = arrayFields.has(camelCaseKey) || arrayFields.has(optionName)
+          const isArray =
+            arrayFields.has(camelCaseKey) || arrayFields.has(optionName)
 
           if (isArray) {
             // For array fields, accumulate values
@@ -298,7 +327,10 @@ export class CliParserService {
   }
 
   /**
-   * Formats help text for available commands
+   * 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:', '']

package/src/services/module-loader.service.mts

@@ -1,8 +1,8 @@
-import type { ClassTypeWithInstance } from '@navios/di'
+import type { ClassTypeWithInstance, 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 type { CliModuleMetadata, CommandMetadata } from '../metadata/index.mjs'
 
 import {
@@ -10,20 +10,46 @@ import {
   extractCommandMetadata,
 } from '../metadata/index.mjs'
 
+/**
+ * Command class with its associated metadata.
+ *
+ * @public
+ */
 export interface CommandWithMetadata {
+  /**
+   * The command class constructor.
+   */
   class: ClassTypeWithInstance<CommandHandler>
+  /**
+   * The command metadata including path and options schema.
+   */
   metadata: CommandMetadata
 }
 
+/**
+ * Service for loading and managing CLI modules and commands.
+ *
+ * Handles module traversal, command registration, and metadata collection.
+ * This service is used internally by CommanderApplication.
+ *
+ * @public
+ */
 @Injectable()
-export class ModuleLoaderService {
+export class CliModuleLoaderService {
   protected container = inject(Container)
   private modulesMetadata: Map<string, CliModuleMetadata> = new Map()
   private loadedModules: Map<string, any> = new Map()
   private commandsMetadata: Map<string, CommandWithMetadata> = new Map()
   private initialized = false
 
-  async loadModules(appModule: ClassTypeWithInstance<Module>) {
+  /**
+   * Loads all modules starting from the root app module.
+   *
+   * Traverses the module tree, loads imported modules, and collects command metadata.
+   *
+   * @param appModule - The root CLI module
+   */
+  async loadModules(appModule: ClassTypeWithInstance<NaviosModule>) {
     if (this.initialized) {
       return
     }
@@ -32,7 +58,7 @@ export class ModuleLoaderService {
   }
 
   private async traverseModules(
-    module: ClassTypeWithInstance<Module>,
+    module: ClassTypeWithInstance<NaviosModule>,
     parentMetadata?: CliModuleMetadata,
   ) {
     const metadata = extractCliModuleMetadata(module)
@@ -80,10 +106,20 @@ export class ModuleLoaderService {
     }
   }
 
+  /**
+   * Gets all loaded module metadata.
+   *
+   * @returns Map of module names to their metadata
+   */
   getAllModules(): Map<string, CliModuleMetadata> {
     return this.modulesMetadata
   }
 
+  /**
+   * Gets all command classes indexed by command class name.
+   *
+   * @returns Map of command class names to command classes
+   */
   getAllCommands(): Map<string, ClassTypeWithInstance<any>> {
     const commands = new Map<string, ClassTypeWithInstance<any>>()
     for (const metadata of this.modulesMetadata.values()) {
@@ -111,6 +147,9 @@ export class ModuleLoaderService {
     return this.commandsMetadata.get(path)
   }
 
+  /**
+   * Disposes of all loaded modules and commands, clearing internal state.
+   */
   dispose() {
     this.modulesMetadata.clear()
     this.loadedModules.clear()

package/src/tokens/execution-context.token.mts

@@ -0,0 +1,34 @@
+import { InjectionToken } from '@navios/core'
+
+import type { CommanderExecutionContext } from '../interfaces/index.mjs'
+
+const CommandExecutionContextInjectionToken =
+  'CommanderExecutionContextInjectionToken'
+
+/**
+ * Injection token for accessing the current command execution context.
+ *
+ * Use this token with `inject()` to access the `CommanderExecutionContext` in services
+ * that need information about the currently executing command.
+ *
+ * @example
+ * ```typescript
+ * import { inject, Injectable } from '@navios/di'
+ * import { CommandExecutionContext } from '@navios/commander'
+ *
+ * @Injectable()
+ * class MyService {
+ *   private ctx = inject(CommandExecutionContext)
+ *
+ *   doSomething() {
+ *     const commandPath = this.ctx.getCommandPath()
+ *     const options = this.ctx.getOptions()
+ *     // Use context information...
+ *   }
+ * }
+ * ```
+ */
+export const CommandExecutionContext =
+  InjectionToken.create<CommanderExecutionContext>(
+    CommandExecutionContextInjectionToken,
+  )

package/src/tokens/index.mts

@@ -0,0 +1 @@
+export * from './execution-context.token.mjs'

package/tsdown.config.mts

@@ -0,0 +1,33 @@
+import { withFilter } from 'rolldown/filter'
+import { defineConfig } from 'tsdown'
+import swc from 'unplugin-swc'
+
+export default defineConfig({
+  entry: ['src/index.mts'],
+  outDir: 'lib',
+  format: ['esm', 'cjs'],
+  clean: true,
+  treeshake: true,
+  sourcemap: true,
+  platform: 'node',
+  dts: true,
+  target: 'es2022',
+  plugins: [
+    withFilter(
+      swc.rolldown({
+        jsc: {
+          target: 'es2022',
+          parser: {
+            syntax: 'typescript',
+            decorators: true,
+          },
+          transform: {
+            decoratorVersion: '2022-03',
+          },
+        },
+      }),
+      // Only run this transform if the file contains a decorator.
+      { transform: { code: '@' } },
+    ),
+  ],
+})