@navios/commander 0.5.0

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

@@ -0,0 +1,404 @@
+import { Container } from '@navios/di'
+
+import { beforeEach, describe, expect, it } from 'vitest'
+import { z } from 'zod'
+
+import { CliParserService } from '../cli-parser.service.mjs'
+
+describe('CliParserService', () => {
+  let parser: CliParserService
+  beforeEach(async () => {
+    const container = new Container()
+    parser = await container.get(CliParserService)
+  })
+
+  describe('basic parsing', () => {
+    it('should parse simple command', () => {
+      const result = parser.parse(['node', 'script.js', 'test'])
+      expect(result.command).toBe('test')
+      expect(result.options).toEqual({})
+      expect(result.positionals).toEqual([])
+    })
+
+    it('should parse multi-word command', () => {
+      const result = parser.parse(['node', 'script.js', 'db', 'migrate'])
+      expect(result.command).toBe('db migrate')
+      expect(result.options).toEqual({})
+      expect(result.positionals).toEqual([])
+    })
+
+    it('should parse command with long options', () => {
+      const result = parser.parse(['node', 'script.js', 'test', '--verbose'])
+      expect(result.command).toBe('test')
+      expect(result.options).toEqual({ verbose: true })
+    })
+
+    it('should parse command with long options and values', () => {
+      const result = parser.parse([
+        'node',
+        'script.js',
+        'test',
+        '--config',
+        'prod',
+      ])
+      expect(result.command).toBe('test')
+      expect(result.options).toEqual({ config: 'prod' })
+    })
+
+    it('should parse command with kebab-case options to camelCase', () => {
+      const result = parser.parse(['node', 'script.js', 'test', '--dry-run'])
+      expect(result.command).toBe('test')
+      expect(result.options).toEqual({ dryRun: true })
+    })
+
+    it('should parse command with short options', () => {
+      const result = parser.parse(['node', 'script.js', 'test', '-v'])
+      expect(result.command).toBe('test')
+      expect(result.options).toEqual({ v: true })
+    })
+
+    it('should parse command with short options and values', () => {
+      const result = parser.parse(['node', 'script.js', 'test', '-c', 'prod'])
+      expect(result.command).toBe('test')
+      expect(result.options).toEqual({ c: 'prod' })
+    })
+
+    it('should parse multiple short flags', () => {
+      const result = parser.parse(['node', 'script.js', 'test', '-abc'])
+      expect(result.command).toBe('test')
+      expect(result.options).toEqual({ a: true, b: true, c: true })
+    })
+
+    it('should parse mixed options and positionals', () => {
+      const result = parser.parse(
+        [
+          'node',
+          'script.js',
+          'test',
+          '--verbose',
+          'file1',
+          '-c',
+          'prod',
+          'file2',
+        ],
+        z.object({
+          verbose: z.boolean(),
+          c: z.string(),
+        }),
+      )
+      expect(result.command).toBe('test')
+      expect(result.options).toEqual({ verbose: true, c: 'prod' })
+      expect(result.positionals).toEqual(['file1', 'file2'])
+    })
+
+    it('should parse options with equal sign syntax', () => {
+      const result = parser.parse([
+        'node',
+        'script.js',
+        'test',
+        '--config=prod',
+        '--port=3000',
+      ])
+      expect(result.command).toBe('test')
+      expect(result.options).toEqual({ config: 'prod', port: 3000 })
+    })
+
+    it('should throw error when no command provided', () => {
+      expect(() => parser.parse(['node', 'script.js'])).toThrow(
+        '[Navios Commander] No command provided',
+      )
+    })
+  })
+
+  describe('value type parsing', () => {
+    it('should parse boolean values', () => {
+      const result = parser.parse([
+        'node',
+        'script.js',
+        'test',
+        '--flag',
+        'true',
+        '--other',
+        'false',
+      ])
+      expect(result.options).toEqual({ flag: true, other: false })
+    })
+
+    it('should parse integer values', () => {
+      const result = parser.parse([
+        'node',
+        'script.js',
+        'test',
+        '--port',
+        '3000',
+      ])
+      expect(result.options).toEqual({ port: 3000 })
+    })
+
+    it('should parse negative integer values', () => {
+      const result = parser.parse([
+        'node',
+        'script.js',
+        'test',
+        '--offset',
+        '"-10"',
+      ])
+      expect(result.options).toEqual({ offset: '"-10"' })
+    })
+
+    it('should parse float values', () => {
+      const result = parser.parse([
+        'node',
+        'script.js',
+        'test',
+        '--ratio',
+        '3.14',
+      ])
+      expect(result.options).toEqual({ ratio: 3.14 })
+    })
+
+    it('should parse null value', () => {
+      const result = parser.parse([
+        'node',
+        'script.js',
+        'test',
+        '--value',
+        'null',
+      ])
+      expect(result.options).toEqual({ value: null })
+    })
+
+    it('should parse JSON object', () => {
+      const result = parser.parse([
+        'node',
+        'script.js',
+        'test',
+        '--data',
+        '{"key":"value"}',
+      ])
+      expect(result.options).toEqual({ data: { key: 'value' } })
+    })
+
+    it('should parse JSON array', () => {
+      const result = parser.parse([
+        'node',
+        'script.js',
+        'test',
+        '--items',
+        '[1,2,3]',
+      ])
+      expect(result.options).toEqual({ items: [1, 2, 3] })
+    })
+  })
+
+  describe('schema-aware parsing', () => {
+    it('should detect boolean flags from schema', () => {
+      const schema = z.object({
+        verbose: z.boolean(),
+        config: z.string(),
+      })
+
+      const result = parser.parse(
+        ['node', 'script.js', 'test', '--verbose', '--config', 'prod'],
+        schema,
+      )
+
+      expect(result.options).toEqual({
+        verbose: true,
+        config: 'prod',
+      })
+    })
+
+    it('should handle optional boolean flags', () => {
+      const schema = z.object({
+        verbose: z.boolean().optional(),
+        dryRun: z.boolean().optional(),
+        config: z.string(),
+      })
+
+      const result = parser.parse(
+        [
+          'node',
+          'script.js',
+          'test',
+          '--verbose',
+          '--dry-run',
+          '--config',
+          'prod',
+        ],
+        schema,
+      )
+
+      expect(result.options).toEqual({
+        verbose: true,
+        dryRun: true,
+        config: 'prod',
+      })
+    })
+
+    it('should handle default boolean flags', () => {
+      const schema = z.object({
+        verbose: z.boolean().default(false),
+        config: z.string(),
+      })
+
+      const result = parser.parse(
+        ['node', 'script.js', 'test', '--verbose', '--config', 'prod'],
+        schema,
+      )
+
+      expect(result.options).toEqual({
+        verbose: true,
+        config: 'prod',
+      })
+    })
+
+    it('should prevent boolean flag from consuming next option as value', () => {
+      const schema = z.object({
+        verbose: z.boolean(),
+        debug: z.boolean(),
+        config: z.string(),
+      })
+
+      // Without schema, --verbose would incorrectly consume '--debug' as its value
+      const result = parser.parse(
+        [
+          'node',
+          'script.js',
+          'test',
+          '--verbose',
+          '--debug',
+          '--config',
+          'prod',
+        ],
+        schema,
+      )
+
+      expect(result.options).toEqual({
+        verbose: true,
+        debug: true,
+        config: 'prod',
+      })
+    })
+
+    it('should handle mixed boolean and non-boolean options', () => {
+      const schema = z.object({
+        verbose: z.boolean(),
+        port: z.number(),
+        host: z.string(),
+        dryRun: z.boolean(),
+      })
+
+      const result = parser.parse(
+        [
+          'node',
+          'script.js',
+          'test',
+          '--verbose',
+          '--port',
+          '3000',
+          '--host',
+          'localhost',
+          '--dry-run',
+        ],
+        schema,
+      )
+
+      expect(result.options).toEqual({
+        verbose: true,
+        port: 3000,
+        host: 'localhost',
+        dryRun: true,
+      })
+    })
+
+    it('should work without schema (fallback behavior)', () => {
+      const result = parser.parse([
+        'node',
+        'script.js',
+        'test',
+        '--verbose',
+        '--config',
+        'prod',
+      ])
+
+      // Without schema, parser uses heuristics
+      expect(result.options).toEqual({
+        verbose: true,
+        config: 'prod',
+      })
+    })
+
+    it('should handle short boolean flags from schema', () => {
+      const schema = z.object({
+        v: z.boolean(),
+        c: z.string(),
+      })
+
+      const result = parser.parse(
+        ['node', 'script.js', 'test', '-v', '-c', 'prod'],
+        schema,
+      )
+
+      expect(result.options).toEqual({
+        v: true,
+        c: 'prod',
+      })
+    })
+
+    it('should handle complex schema with nested optional booleans', () => {
+      const schema = z.object({
+        verbose: z.boolean().optional(),
+        debug: z.boolean().default(false),
+        quiet: z.boolean(),
+        config: z.string(),
+        port: z.number().optional(),
+      })
+
+      const result = parser.parse(
+        [
+          'node',
+          'script.js',
+          'test',
+          '--verbose',
+          '--debug',
+          '--quiet',
+          '--config',
+          'production',
+        ],
+        schema,
+      )
+
+      expect(result.options).toEqual({
+        verbose: true,
+        debug: true,
+        quiet: true,
+        config: 'production',
+      })
+    })
+  })
+
+  describe('edge cases', () => {
+    it('should handle command followed immediately by options', () => {
+      const result = parser.parse(['node', 'script.js', 'test', '--flag'])
+      expect(result.command).toBe('test')
+      expect(result.options).toEqual({ flag: true })
+    })
+
+    it('should handle options with dashes in values', () => {
+      const result = parser.parse([
+        'node',
+        'script.js',
+        'test',
+        '--branch',
+        'feature-test',
+      ])
+      expect(result.options).toEqual({ branch: 'feature-test' })
+    })
+
+    it('should handle single dash as positional', () => {
+      const result = parser.parse(['node', 'script.js', 'test', '-'])
+      expect(result.positionals).toEqual(['-'])
+    })
+  })
+})

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

@@ -0,0 +1,231 @@
+import type { ZodObject, ZodType } from 'zod'
+
+import { Injectable } from '@navios/di'
+
+export interface ParsedCliArgs {
+  command: string
+  options: Record<string, any>
+  positionals: string[]
+}
+
+@Injectable()
+export class CliParserService {
+  /**
+   * Parses command-line arguments from process.argv
+   * Commands can be multi-word (e.g., 'db migrate', 'cache clear')
+   * Expected format: node script.js command [subcommand...] --flag value --boolean-flag positional1 positional2
+   *
+   * @param argv - Array of command-line arguments (typically process.argv)
+   * @param optionsSchema - Optional Zod schema to determine boolean flags and option types
+   * @returns Parsed command (space-separated if multi-word), options, and positional arguments
+   */
+  parse(argv: string[], optionsSchema?: ZodObject): ParsedCliArgs {
+    // Skip first two args (node and script path)
+    const args = argv.slice(2)
+
+    if (args.length === 0) {
+      throw new Error('[Navios Commander] No command provided')
+    }
+
+    // Extract boolean field names from schema for accurate parsing
+    const booleanFields = optionsSchema
+      ? this.extractBooleanFields(optionsSchema)
+      : new Set<string>()
+
+    // Collect command words until we hit an argument that starts with '-' or '--'
+    const commandParts: string[] = []
+    let i = 0
+    while (i < args.length && !args[i].startsWith('-')) {
+      commandParts.push(args[i])
+      i++
+    }
+
+    if (commandParts.length === 0) {
+      throw new Error('[Navios Commander] No command provided')
+    }
+
+    const command = commandParts.join(' ')
+    const options: Record<string, any> = {}
+    const positionals: string[] = []
+    while (i < args.length) {
+      const arg = args[i]
+
+      if (arg.startsWith('--')) {
+        // Long option format: --key=value or --key value
+        const key = arg.slice(2)
+        const equalIndex = key.indexOf('=')
+
+        if (equalIndex !== -1) {
+          // Format: --key=value
+          const optionName = key.slice(0, equalIndex)
+          const optionValue = key.slice(equalIndex + 1)
+          options[this.camelCase(optionName)] = this.parseValue(optionValue)
+          i++
+        } else {
+          // Format: --key value or --boolean-flag
+          const camelCaseKey = this.camelCase(key)
+          const isBoolean =
+            booleanFields.has(camelCaseKey) || booleanFields.has(key)
+          const nextArg = args[i + 1]
+
+          if (isBoolean) {
+            // Known boolean flag from schema
+            options[camelCaseKey] = true
+            i++
+          } else if (nextArg && !nextArg.startsWith('-')) {
+            // Has a value
+            options[camelCaseKey] = this.parseValue(nextArg)
+            i += 2
+          } else {
+            // Assume boolean flag
+            options[camelCaseKey] = true
+            i++
+          }
+        }
+      } else if (arg.startsWith('-') && arg.length > 1 && arg !== '-') {
+        // Short option format: -k value or -abc (multiple flags)
+        const flags = arg.slice(1)
+
+        if (flags.length === 1) {
+          // Single short flag: -k value or -k
+          const isBoolean = booleanFields.has(flags)
+          const nextArg = args[i + 1]
+
+          if (isBoolean) {
+            // Known boolean flag from schema
+            options[flags] = true
+            i++
+          } else if (nextArg && !nextArg.startsWith('-')) {
+            options[flags] = this.parseValue(nextArg)
+            i += 2
+          } else {
+            options[flags] = true
+            i++
+          }
+        } else {
+          // Multiple short flags: -abc -> {a: true, b: true, c: true}
+          for (const flag of flags) {
+            options[flag] = true
+          }
+          i++
+        }
+      } else {
+        // Positional argument
+        positionals.push(arg)
+        i++
+      }
+    }
+
+    return {
+      command,
+      options,
+      positionals,
+    }
+  }
+
+  /**
+   * Converts kebab-case to camelCase
+   */
+  private camelCase(str: string): string {
+    return str.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase())
+  }
+
+  /**
+   * Attempts to parse string values into appropriate types
+   */
+  private parseValue(value: string): any {
+    // Check for boolean
+    if (value === 'true') return true
+    if (value === 'false') return false
+
+    // Check for null/undefined
+    if (value === 'null') return null
+    if (value === 'undefined') return undefined
+
+    // Check for number
+    if (/^-?\d+$/.test(value)) {
+      return parseInt(value, 10)
+    }
+    if (/^-?\d+\.\d+$/.test(value)) {
+      return parseFloat(value)
+    }
+
+    // Check for JSON
+    if (
+      (value.startsWith('{') && value.endsWith('}')) ||
+      (value.startsWith('[') && value.endsWith(']'))
+    ) {
+      try {
+        return JSON.parse(value)
+      } catch {
+        // If parsing fails, return as string
+        return value
+      }
+    }
+
+    // Return as string
+    return value
+  }
+
+  /**
+   * Extracts boolean field names from a Zod schema
+   * Handles ZodObject, ZodOptional, and ZodDefault wrappers
+   */
+  private extractBooleanFields(schema: ZodObject): Set<string> {
+    const booleanFields = new Set<string>()
+
+    try {
+      // Check if schema has _def.typeName (Zod schema structure)
+      const typeName = schema.def.type
+
+      if (typeName === 'object') {
+        // Extract shape from ZodObject
+        const shape = schema.def.shape
+
+        if (shape && typeof shape === 'object') {
+          for (const [key, fieldSchema] of Object.entries(shape)) {
+            if (this.isSchemaBoolean(fieldSchema as any)) {
+              booleanFields.add(key)
+            }
+          }
+        }
+      }
+    } catch {
+      // Silently fail if schema introspection fails
+    }
+
+    return booleanFields
+  }
+
+  /**
+   * Checks if a Zod schema represents a boolean type
+   * Unwraps ZodOptional and ZodDefault
+   */
+  private isSchemaBoolean(schema: ZodType): boolean {
+    try {
+      let currentSchema = schema
+      const typeName = currentSchema.def.type
+
+      // Unwrap ZodOptional and ZodDefault
+      if (typeName === 'optional' || typeName === 'default') {
+        currentSchema = (currentSchema as any)?._def?.innerType || currentSchema
+      }
+
+      const innerTypeName = currentSchema.def.type
+      return innerTypeName === 'boolean'
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Formats help text for available 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')
+  }
+}

package/src/services/index.mts

@@ -0,0 +1,2 @@
+export * from './module-loader.service.mjs'
+export * from './cli-parser.service.mjs'