@rsdk/cli.core 5.7.0-next.2 → 6.0.0-next.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsdk/cli.core",
-  "version": "5.7.0-next.2",
+  "version": "6.0.0-next.0",
   "description": "entry package to cli functions",
   "main": "dist/index.js",
   "publishConfig": {
@@ -12,15 +12,28 @@
   ],
   "license": "Apache License 2.0",
   "dependencies": {
-    "@rsdk/cli.common": "5.7.0-next.2",
-    "@rsdk/logging": "5.7.0-next.2",
-    "commander": "^12.1.0"
+    "@rsdk/cli.common": "6.0.0-next.0",
+    "@rsdk/common": "6.0.0-next.0",
+    "@rsdk/env": "6.0.0-next.0",
+    "@rsdk/logging": "6.0.0-next.0",
+    "commander": "^12.1.0",
+    "lodash": "^4.17.21"
   },
   "peerDependencies": {
     "@rsdk/cli.common": "*",
     "@rsdk/logging": "*",
     "commander": "^12.1.0",
-    "reflect-metadata": "^0.1.12 || ^0.2.0"
+    "reflect-metadata": "^0.1.12 || ^0.2.0",
+    "ts-node": "10.9.2",
+    "typescript": "5.7.3"
+  },
+  "peerDependenciesMeta": {
+    "ts-node": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
+    }
   },
-  "gitHead": "c85fca0b594a2ea168d06f1d2941a4fb05b59440"
+  "gitHead": "215cccea23d95118dd8b6af3ce11c6a35ce19c30"
 }

package/src/cli.ts

@@ -1,54 +1,68 @@
-import type { RsdkCliCommand } from '@rsdk/cli.common';
-import { program } from 'commander';
+import type { IRunnable } from '@rsdk/cli.common';
+import { MetadataRegistry } from '@rsdk/cli.common';
+import { Assert, type Constructor } from '@rsdk/common';
+import { Env } from '@rsdk/env';
+import type { ILogger } from '@rsdk/logging';
+import type { Command } from 'commander';
+
+import { CommandResolver } from './resolvers/command.resolver';
+import { OptionsResolver } from './resolvers/options.resolver';
+import { LocalPathLoader, PkgLoader } from './loaders';
+
+export interface CliOptions {
+  plugins?: (string | { command: any; cmd: string })[];
+  discoverPlugins?: boolean;
+  cliPackageName: string;
+}
 
 export class Cli {
   constructor(
-    readonly opts?: {
-      plugins?: (string | { command: RsdkCliCommand; cmd: string })[];
-      discoverPlugins?: boolean;
-      cliPackageName: string;
-    },
+    private readonly program: Command,
+    private readonly logger: ILogger,
+    private readonly opts?: CliOptions,
   ) {}
 
-  async handle(argv: string[]): Promise<void> {
-    const rsdkCommand = argv.slice(2)[0];
+  async handle(arg: string | undefined): Promise<void> {
+    try {
+      if (!arg || arg.startsWith('-')) {
+        await this.program.parseAsync();
+        return;
+      }
 
-    if (!rsdkCommand || rsdkCommand.startsWith('-')) {
-      program.parse();
-      return;
-    }
-    const cmd = rsdkCommand.split(':')[0];
+      const env = new Env();
+      const optionsResolver = new OptionsResolver(env, this.logger);
+      const commandResolver = new CommandResolver(optionsResolver, this.logger);
 
-    const rsdkCliCommandName = this.getCmdPackageName(cmd);
-    let rsdkCliCommand;
+      const command = await this.loadCommand(arg);
 
-    try {
-      // eslint-disable-next-line @typescript-eslint/no-var-requires
-      rsdkCliCommand = require(rsdkCliCommandName);
+      const { subcommands, variations } = MetadataRegistry.getCommand(command);
+
+      this.program.addCommand(commandResolver.resolve(command, subcommands));
+
+      for (const command of variations || []) {
+        this.program.addCommand(commandResolver.resolve(command));
+      }
+
+      await this.program.parseAsync();
     } catch (error) {
-      throw new Error(
-        'Error on require module, try install it `yarn add -D ' +
-          rsdkCliCommandName,
-        {
-          cause: error,
-        },
-      );
-    }
-    if (!('Cmd' in rsdkCliCommand)) {
-      throw new Error('Invalid cli cmd package', {
-        cause: { rsdkCliCommand, rsdkCliCommandName },
-      });
+      Assert.isError(error);
+      this.logger.error(error);
     }
-    const cmds = rsdkCliCommand.Cmd.getCommands();
+  }
 
-    for (const cmd of cmds) {
-      program.addCommand(cmd);
-    }
+  private async loadCommand(
+    rsdkCommand: string,
+  ): Promise<Constructor<IRunnable>> {
+    const [cmd] = rsdkCommand.split(':');
+
+    const loader = this.isLocalPath(cmd)
+      ? new LocalPathLoader()
+      : new PkgLoader(this.opts?.cliPackageName);
 
-    program.parse();
+    return await loader.load(cmd);
   }
 
-  private getCmdPackageName(cmd: string): string {
-    return [this.opts?.cliPackageName, 'cmd', cmd].join('.');
+  private isLocalPath(cmd: string): boolean {
+    return cmd.startsWith('./') || cmd.startsWith('/') || cmd.includes('\\');
   }
 }

package/src/index.ts

@@ -1,4 +1,5 @@
-import type { RsdkCliCommand } from '@rsdk/cli.common';
+import { LoggerFactory } from '@rsdk/logging';
+import { program } from 'commander';
 import path from 'node:path';
 
 import './reconfigure-logger';
@@ -14,13 +15,20 @@ const getCliPackageName = (): string => {
   ).name;
 };
 
+/**
+ * Выполняет команду
+ */
 export const execute = async (opts?: {
-  plugins?: (string | { command: RsdkCliCommand; cmd: string })[];
+  plugins?: (string | { command: any; cmd: string })[];
   discoverPlugins?: boolean;
   scope?: string;
 }): Promise<void> => {
   const cliPackageName = opts?.scope ?? getCliPackageName();
 
   process.title = cliPackageName.split('/')[0].slice(1);
-  await new Cli({ ...opts, cliPackageName }).handle(process.argv);
+
+  const logger = LoggerFactory.create(cliPackageName);
+  const cli = new Cli(program, logger, { ...opts, cliPackageName });
+
+  await cli.handle(process.argv.at(2));
 };

package/src/loaders/implementations/index.ts

@@ -0,0 +1,2 @@
+export * from './local-path.loader';
+export * from './pkg.loader';

package/src/loaders/implementations/local-path.loader.ts

@@ -0,0 +1,53 @@
+import type { Constructor } from '@rsdk/common';
+import path from 'node:path';
+
+import type { ICommandLoader } from '../loader.interface';
+
+/**
+ * Загружает команды из файла
+ */
+export class LocalPathLoader implements ICommandLoader {
+  async load(filename: string): Promise<Constructor> {
+    const resolvedPath = path.isAbsolute(filename)
+      ? filename
+      : path.resolve(process.cwd(), filename);
+
+    try {
+      // Регистрируем ts-node до импорта файла
+      if (resolvedPath.endsWith('.ts')) {
+        this.registerTsNode(resolvedPath);
+      }
+
+      const { default: command } = await require(resolvedPath);
+
+      return command;
+    } catch (error) {
+      throw new Error(`Error loading command from file: ${resolvedPath}`, {
+        cause: error,
+      });
+    }
+  }
+
+  private registerTsNode(resolvedPath: string): void {
+    /* eslint-disable @typescript-eslint/no-var-requires */
+    const tsnode = require('ts-node');
+    const typescript = require('typescript');
+    /* eslint-enable @typescript-eslint/no-var-requires */
+
+    // Ищем ближайший tsconfig.json
+    const tsconfigPath = typescript.findConfigFile(
+      path.dirname(resolvedPath),
+      typescript.sys.fileExists,
+    );
+
+    tsnode.register({
+      transpileOnly: true, // Для более быстрой компиляции
+      project: tsconfigPath || undefined, // Используем найденный tsconfig или undefined
+      compilerOptions: {
+        // Базовые опции, которые будут перезаписаны настройками из tsconfig
+        module: 'commonjs',
+        target: 'es2017',
+      },
+    });
+  }
+}

package/src/loaders/implementations/pkg.loader.ts

@@ -0,0 +1,33 @@
+import type { IRunnable } from '@rsdk/cli.common';
+import type { Constructor } from '@rsdk/common';
+
+import type { ICommandLoader } from '../loader.interface';
+
+/**
+ * Загружает команды из пакета
+ */
+export class PkgLoader implements ICommandLoader {
+  constructor(private readonly cliPackageName?: string) {}
+
+  async load(cmd: string): Promise<Constructor<IRunnable>> {
+    /* Пример вызова из консоли:
+     * $ rsdk init
+     * где:
+     * cliPackageName = '@rsdk/cli'
+     * cmd = 'init'
+     * pkg = '@rsdk/cli.cmd.init'
+     */
+    const pkg = [this.cliPackageName, 'cmd', cmd].join('.');
+
+    try {
+      const { default: command } = await require(pkg);
+
+      return command;
+    } catch (error) {
+      throw new Error(
+        `Error loading package, try install it: yarn add -D ${pkg}`,
+        { cause: error },
+      );
+    }
+  }
+}

package/src/loaders/index.ts

@@ -0,0 +1 @@
+export * from './implementations';

package/src/loaders/loader.interface.ts

@@ -0,0 +1,6 @@
+import type { IRunnable } from '@rsdk/cli.common';
+import type { Constructor } from '@rsdk/common';
+
+export interface ICommandLoader {
+  load(cmd: string): Promise<Constructor<IRunnable>>;
+}

package/src/resolvers/command.resolver.ts

@@ -0,0 +1,103 @@
+import type { Type } from '@nestjs/common';
+import type {
+  IRunnable,
+  OptionMetadata,
+  ParameterIndex,
+} from '@rsdk/cli.common';
+import { MetadataRegistry } from '@rsdk/cli.common';
+import type { Constructor } from '@rsdk/common';
+import type { ILogger } from '@rsdk/logging';
+import { Command } from 'commander';
+import _ from 'lodash';
+
+import type { OptionsResolver } from './options.resolver';
+
+/**
+ * Класс для преобразования классов команд в стиле rsdk в объекты Commander.Command.
+ * Обрабатывает метаданные команд, опций и подкоманд,
+ * создавая соответствующую структуру.
+ */
+export class CommandResolver {
+  constructor(
+    private readonly optionsResolver: OptionsResolver,
+    private readonly logger: ILogger,
+  ) {}
+
+  /**
+   * Преобразует класс с декоратором @Cmd в объект Commander.Command.
+   * Создает команду с опциями и подкомандами на основе метаданных класса.
+   *
+   * @param {Type} ctor - Конструктор класса команды
+   * @returns {Command} Объект Commander.Command с настроенными опциями и подкомандами
+   * @throws {Error} Если не найдены метаданные команды (отсутствует декоратор @Cmd)
+   */
+  resolve(
+    ctor: Constructor<IRunnable>,
+    subcommands: Constructor<IRunnable>[] = [],
+  ): Command {
+    this.logger.trace('resolving command', { ctor });
+    this.assertNoParams(ctor);
+
+    const command = this.createCommand(ctor);
+
+    for (const subcommand of subcommands) {
+      command.addCommand(this.createCommand(subcommand));
+    }
+
+    return command;
+  }
+
+  private createCommand(ctor: Type): Command {
+    // Duplication
+    const commandMetadata = MetadataRegistry.getRunnable(ctor);
+
+    const instance = Reflect.construct(ctor, []);
+    if (typeof instance['run'] !== 'function') {
+      throw new TypeError('Command must implement "run" method');
+    }
+
+    const { name, description } = commandMetadata;
+    const command = new Command(name).description(description);
+
+    const options = MetadataRegistry.getOptions(ctor);
+
+    for (const option of options.values()) {
+      const envKey = this.optionsResolver.createEnvKey(option);
+      const optionName = `--${option.name}${option.parser ? ' <value>' : ''}`;
+      const optionDescription = `${option.description} [eq ${envKey} in env]`;
+
+      command.option(optionName, optionDescription, option.defaultValue);
+    }
+
+    command.action(this.createHandler(options, instance['run'].bind(instance)));
+
+    return command;
+  }
+
+  private createHandler(
+    optionsByIndex: Map<ParameterIndex, OptionMetadata>,
+    method: (...args: any[]) => any,
+  ) {
+    return (__: any, cmd: Command): any => {
+      /* Преобразуем опции в массив аргументов для вызова метода:
+       * 1. Конвертируем Map в массив пар [индекс, метаданные]
+       * 2. Получаем значения опций через OptionsResolver
+       * (с учетом приоритета источников)
+       * 3. Сортируем по индексу для правильного порядка аргументов
+       */
+      const args = _([...optionsByIndex])
+        .map(([index, metadata]) => ({ index, metadata }))
+        .sortBy((x) => x.index)
+        .map((x) => this.optionsResolver.resolve(x.metadata, cmd.opts()));
+
+      return method(...args.value());
+    };
+  }
+
+  private assertNoParams(ctor: Type): void {
+    const paramTypes = Reflect.getMetadata('design:paramtypes', ctor);
+    if (paramTypes?.length > 0) {
+      throw new Error('Command constructor must have no parameters');
+    }
+  }
+}

package/src/resolvers/options.resolver.ts

@@ -0,0 +1,92 @@
+import type { OptionMetadata } from '@rsdk/cli.common';
+import { BoolParser, Case } from '@rsdk/common';
+import type { Env } from '@rsdk/env';
+import type { ILogger } from '@rsdk/logging';
+import type { OptionValues } from 'commander';
+import _ from 'lodash';
+
+/**
+ * Класс для разрешения значений опций командной строки.
+ * Обрабатывает значения из трех источников: переменные окружения, флаги командной строки и значения по умолчанию.
+ */
+export class OptionsResolver {
+  constructor(
+    private readonly env: Env,
+    private readonly logger: ILogger,
+  ) {}
+
+  /**
+   * Разрешает значение опции командной строки на основе метаданных и переданных параметров.
+   * Проверяет три источника значений в порядке приоритета:
+   * 1. Переменные окружения
+   * 2. Флаги командной строки
+   * 3. Значения по умолчанию
+   *
+   * Такой приоритет выбран для удобства конфигурирования в разных окружениях:
+   * - В локальной разработке проблем с ENV обычно не возникает
+   * - В Kubernetes удобнее редактировать ConfigMap, чем Deployment
+   * @param {OptionMetadata} optionMetadata - Метаданные опции, содержащие имя, парсер и значение по умолчанию
+   * @param {OptionValues} passedOptions - Объект с переданными опциями командной строки
+   * @returns {any} Разрешенное значение опции
+   */
+  resolve(optionMetadata: OptionMetadata, passedOptions: OptionValues): any {
+    this.logger.trace('handle arg', { optionMetadata });
+
+    const parser = optionMetadata.parser ?? new BoolParser();
+
+    // Находим значение переменной окружения
+    const envKey = this.createEnvKey(optionMetadata);
+    const variable = this.env.optional(envKey, parser);
+
+    // Находим значение переданное в виде флага
+    const optsKey = _.camelCase(optionMetadata.name);
+    const isPassed = Object.hasOwn(passedOptions, optsKey);
+    const valueFromFlag = passedOptions[optsKey];
+
+    if (variable) {
+      if (isPassed) {
+        this.logger.warn(
+          `Environment variable ${envKey} overrides command flags`,
+        );
+      }
+
+      // Возвращаем значение переменной окружения
+      return variable.value;
+    }
+
+    this.logger.trace(`Environment variable ${envKey} not provided`);
+
+    if (isPassed) {
+      this.logger.trace(`Use flag value: ${valueFromFlag}`, {
+        key: optsKey,
+        opts: passedOptions,
+      });
+
+      return parser.parse(valueFromFlag);
+    }
+
+    const defaultValue = optionMetadata.defaultValue;
+
+    this.logger.trace(`Use default value: ${defaultValue}`, {
+      key: optsKey,
+      opts: passedOptions,
+    });
+
+    /**
+     * undefined - вполне нормально значение по умолчанию
+     */
+    return defaultValue === undefined ? undefined : parser.parse(defaultValue);
+  }
+
+  /**
+   * Создает ключ переменной окружения на основе метаданных опции.
+   *
+   * @param {OptionMetadata} optionMetadata - Метаданные опции, содержащие имя и стратегию.
+   * @returns {string} Ключ переменной окружения в формате верхнего регистра с подчеркиванием.
+   */
+  createEnvKey(optionMetadata: OptionMetadata): string {
+    return Case.toUpperSnake(
+      `${optionMetadata.name}${optionMetadata.parser ? '' : '_enabled'}`,
+    );
+  }
+}

package/test/cli.spec.ts

@@ -0,0 +1,131 @@
+import type { ILogger } from '@rsdk/logging';
+import { NoopLogger } from '@rsdk/logging';
+import { Command } from 'commander';
+
+import { Cli } from '../src/cli';
+
+import WithAll from './commands/command.with-all';
+
+describe('Cli', () => {
+  let logger: ILogger;
+  let program: Command;
+  let cli: Cli;
+
+  beforeEach(() => {
+    logger = new NoopLogger();
+    program = new Command();
+
+    // eslint-disable-next-line unicorn/no-useless-undefined
+    program.parseAsync = jest.fn().mockResolvedValue(undefined);
+
+    cli = new Cli(program, logger, {
+      cliPackageName: '@rsdk/cli.core',
+    });
+  });
+
+  beforeEach(() => {
+    // Переопределяем program перед каждым тестом
+    jest.resetModules();
+  });
+
+  describe('handle', () => {
+    describe('when loading command with subcommands and variations', () => {
+      beforeEach(async () => {
+        const mockLoadCommand = jest.spyOn(cli as any, 'loadCommand');
+
+        mockLoadCommand.mockResolvedValue(WithAll);
+
+        await cli.handle('with-all');
+      });
+
+      it('should load command correctly', () => {
+        const [mainCommand] = program.commands;
+
+        expect(mainCommand.name()).toBe('with-all');
+        expect(mainCommand.description()).toBe(
+          'Test command with subcommands and variations',
+        );
+      });
+
+      it('should register variations correctly', () => {
+        const [, ...variations] = program.commands;
+
+        expect(variations).toHaveLength(2);
+
+        const firstVariation = variations.find(
+          (cmd) => cmd.name() === 'with-variations:first',
+        );
+
+        expect(firstVariation).toBeDefined();
+        expect(firstVariation?.description()).toBe('First variation example');
+
+        const secondVariation = variations.find(
+          (cmd) => cmd.name() === 'with-variations:second',
+        );
+
+        expect(secondVariation).toBeDefined();
+        expect(secondVariation?.description()).toBe('Second variation example');
+      });
+
+      it('should register subcommands correctly', () => {
+        const [mainCommand] = program.commands;
+        const subcommands = mainCommand.commands.filter(
+          (cmd) => cmd.name() !== 'with-all',
+        );
+
+        expect(subcommands).toHaveLength(2);
+
+        const first = subcommands.find(
+          (cmd) => cmd.name() === 'first-subcommand',
+        );
+
+        expect(first).toBeDefined();
+        expect(first?.description()).toBe('First subcommand example');
+
+        const second = subcommands.find(
+          (cmd) => cmd.name() === 'second-subcommand',
+        );
+
+        expect(second).toBeDefined();
+        expect(second?.description()).toBe('Second subcommand example');
+      });
+    });
+
+    describe('error handling', () => {
+      it('should handle command loading errors', async () => {
+        // Arrange
+        const error = new Error('Command load failed');
+        const mockLoadCommand = jest.spyOn(cli as any, 'loadCommand');
+
+        mockLoadCommand.mockRejectedValue(error);
+
+        // Act
+        await cli.handle('invalid-command');
+
+        expect(program.parseAsync).not.toHaveBeenCalled();
+      });
+
+      it('should skip command loading when no arg provided', async () => {
+        // Arrange
+        const mockLoadCommand = jest.spyOn(cli as any, 'loadCommand');
+
+        // Act
+        // eslint-disable-next-line unicorn/no-useless-undefined
+        await cli.handle(undefined);
+
+        expect(mockLoadCommand).not.toHaveBeenCalled();
+      });
+
+      it('should skip command loading when arg starts with -', async () => {
+        // Arrange
+        const mockLoadCommand = jest.spyOn(cli as any, 'loadCommand');
+
+        // Act
+        await cli.handle('--help');
+
+        expect(mockLoadCommand).not.toHaveBeenCalled();
+        expect(program.commands).toHaveLength(0);
+      });
+    });
+  });
+});

package/test/commands/command.single.ts

@@ -0,0 +1,30 @@
+import { Command, IRunnable, Option, ValueOption } from '@rsdk/cli.common';
+import { StringParser } from '@rsdk/common';
+import { LoggerFactory } from '@rsdk/logging';
+
+@Command('cmd-single', {
+  description: 'Test command that logs parameters',
+})
+export default class SingleCommand implements IRunnable {
+  async run(
+    @ValueOption('message', new StringParser(), {
+      description: 'Message to log',
+      defaultValue: 'Hello World!',
+      alias: 'm',
+    })
+    message: string,
+
+    @Option('verbose', { description: 'Verbose output' })
+    verbose: boolean,
+  ): Promise<void> {
+    const logger = LoggerFactory.create(SingleCommand);
+
+    if (verbose) {
+      logger.info('Command parameters:');
+      logger.info(`message: ${message}`);
+      logger.info(`verbose: ${verbose}`);
+    }
+
+    logger.info(message);
+  }
+}