@jumentix/cli-init 0.0.0

package/templates/backend/src/interface/Async/RealtimeAPIBase.ts

@@ -0,0 +1,417 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import fs from 'fs';
+import YAML from 'yaml';
+import { OpenAPIV3 } from 'openapi-types';
+
+import type { IDatabaseClient } from '@src/infra/persistence/port/IDatabaseClient';
+import type { IMutexService } from '@src/infra/mutex/port/IMutexService';
+import type { IPasswordCryptoService } from '@src/infra/security/IPasswordCryptoService';
+import type { IKeyValueStorageClient } from '@src/infra/persistence/KeyValueStorage/IKeyValueStorageClient';
+import { RealtimeDomainEvent } from '@src/interface/Async/RealtimeDomainEvent';
+import type { IAuthService } from '@src/modules/Users';
+import { composeUsersAuthServices } from '@src/modules/Users';
+import type { IEventBus, IMessageMediator } from '@src/modules/port';
+
+export interface IAsyncOperationRequest {
+  version?: string;
+  operationId: string;
+  authorization?: string;
+  input?: Record<string, any>;
+  params?: Record<string, any>;
+  queryString?: Record<string, any>;
+  metadata?: Record<string, any>;
+}
+
+export interface IAsyncOperationResponse {
+  ok: boolean;
+  version?: string;
+  operationId: string;
+  result?: any;
+  metadata?: Record<string, any>;
+  error?: {
+    name: string;
+    message: string;
+  };
+}
+
+export interface IRealtimeAPIFactory {
+  databaseClient: IDatabaseClient;
+  authService?: IAuthService;
+  passwordCryptoService?: IPasswordCryptoService;
+  keyValueStorageClient?: IKeyValueStorageClient;
+  mutexService?: IMutexService;
+  eventBus?: IEventBus;
+  messageMediator?: IMessageMediator;
+  specDir?: string;
+  interfaceType?: 'websocketapi' | 'grpcapi';
+  frameworkName?: string;
+}
+
+export type IRealtimeRuntimeHandler = (
+  request: IAsyncOperationRequest
+) => Promise<IAsyncOperationResponse>;
+
+export interface IRealtimeOperationEntry {
+  version: string;
+  operationId: string;
+  moduleName: string;
+  endPointConfig: Record<string, any>;
+  controller: Record<string, any>;
+  controllerMethod: string;
+  runtimeHandler?: IRealtimeRuntimeHandler;
+}
+
+export interface IRealtimeHandlerFactoryDeps {
+  operationId: string;
+  controllerMethod: string;
+  invoke: IRealtimeRuntimeHandler;
+}
+
+const OPERATION_TO_CONTROLLER_METHOD: Record<string, string> = {
+  deleteOne: 'delete',
+  // SONAR false-positive: this is an operation-id mapping, not a credential literal.
+  updateUserPassword: 'updatePassword' // NOSONAR
+};
+
+export abstract class RealtimeAPIBase {
+  private readonly oas: Map<string, OpenAPIV3.Document> = new Map();
+
+  protected readonly operations: Map<string, IRealtimeOperationEntry> = new Map();
+
+  protected started = false;
+
+  protected readonly databaseClient: IDatabaseClient;
+
+  protected readonly mutexClient?: IMutexService;
+
+  protected readonly authService?: IAuthService;
+
+  protected readonly passwordCryptoService?: IPasswordCryptoService;
+
+  protected readonly keyValueStorageClient?: IKeyValueStorageClient;
+
+  protected eventBus?: IEventBus;
+
+  protected readonly messageMediator?: IMessageMediator;
+
+  private readonly specDir: string;
+
+  private readonly interfaceType?: 'websocketapi' | 'grpcapi';
+
+  private readonly frameworkName?: string;
+
+  private usersComposition: ReturnType<typeof composeUsersAuthServices> | undefined;
+
+  constructor(config: IRealtimeAPIFactory, autoBuild = true) {
+    this.databaseClient = config.databaseClient;
+    this.mutexClient = config.mutexService;
+    this.authService = config.authService;
+    this.passwordCryptoService = config.passwordCryptoService;
+    this.keyValueStorageClient = config.keyValueStorageClient;
+    this.eventBus = config.eventBus;
+    this.messageMediator = config.messageMediator;
+    if (config.messageMediator) {
+      this.eventBus = config.messageMediator;
+    }
+    this.specDir = config.specDir || './spec';
+    this.interfaceType = config.interfaceType;
+    this.frameworkName = config.frameworkName;
+
+    if (autoBuild) {
+      this.buildOperationsFromOAS();
+    }
+  }
+
+  protected composeUsersModule(): ReturnType<typeof composeUsersAuthServices> {
+    if (this.usersComposition) return this.usersComposition;
+    if (!this.passwordCryptoService) {
+      throw new Error('PasswordCryptoService is required to compose Users module.');
+    }
+    if (!this.mutexClient) {
+      throw new Error('MutexService is required to compose Users module.');
+    }
+    if (!this.authService?.jwtService) {
+      throw new Error('AuthService with JwtService is required to compose Users module.');
+    }
+
+    this.usersComposition = composeUsersAuthServices({
+      databaseClient: this.databaseClient,
+      passwordCryptoService: this.passwordCryptoService,
+      mutexService: this.mutexClient,
+      jwtService: this.authService.jwtService,
+      keyValueStorageClient: this.keyValueStorageClient,
+      eventBus: this.eventBus,
+      messageMediator: this.messageMediator
+    });
+
+    return this.usersComposition;
+  }
+
+  protected async executeOperation(
+    request: IAsyncOperationRequest
+  ): Promise<IAsyncOperationResponse> {
+    try {
+      const { operationId, version } = request;
+      const entry = this.resolveOperation(operationId, version);
+      if (!entry) {
+        throw new Error(`Operation "${operationId}" not found.`);
+      }
+
+      const { controllerMethod, controller } = entry;
+      if (entry.runtimeHandler) {
+        return entry.runtimeHandler(request);
+      }
+
+      const method = controller?.[controllerMethod];
+      if (typeof method !== 'function') {
+        throw new Error(
+          `Controller method "${controllerMethod}" not found for operation "${operationId}".`
+        );
+      }
+
+      const event = new RealtimeDomainEvent({
+        authorization: request.authorization || '',
+        input: request.input || {},
+        params: request.params || {},
+        queryString: request.queryString || {},
+        schemaOAS: entry.endPointConfig,
+        entity: entry.moduleName,
+        action: controllerMethod,
+        metadata: request.metadata
+      } as any);
+
+      const serviceResponse = await method.call(controller, event);
+      if (serviceResponse?.error) {
+        throw serviceResponse.error;
+      }
+
+      return {
+        ok: true,
+        version: entry.version,
+        operationId,
+        metadata: request.metadata || {},
+        result: serviceResponse?.result
+      };
+    } catch (error: any) {
+      return {
+        ok: false,
+        version: request.version,
+        operationId: request.operationId,
+        metadata: request.metadata || {},
+        error: {
+          name: error?.name || 'Error',
+          message: error?.message || 'Unknown error'
+        }
+      };
+    }
+  }
+
+  protected registerOperation(entry: IRealtimeOperationEntry): void {
+    const key = `${entry.version}:${entry.operationId}`;
+    this.operations.set(key, entry);
+  }
+
+  protected listOperationIds(): string[] {
+    const set = new Set<string>();
+    for (const entry of this.operations.values()) {
+      set.add(entry.operationId);
+    }
+    return [...set];
+  }
+
+  private resolveOperation(
+    operationId: string,
+    version?: string
+  ): IRealtimeOperationEntry | undefined {
+    if (version) {
+      return this.operations.get(`${version}:${operationId}`);
+    }
+
+    for (const [key, entry] of this.operations) {
+      if (key.endsWith(`:${operationId}`)) {
+        return entry;
+      }
+    }
+    return undefined;
+  }
+
+  private buildOperationsFromOAS(): void {
+    this.loadOpenApiSpecs();
+    for (const [version, spec] of this.oas) {
+      this.registerOperationsFromSpec(version, spec);
+    }
+  }
+
+  private loadOpenApiSpecs(): void {
+    const specs = fs.readdirSync(this.specDir)
+      .filter((fileName) => fileName.endsWith('.yml') || fileName.endsWith('.yaml'));
+
+    for (const fileName of specs) {
+      const file = fs.readFileSync(`${this.specDir}/${fileName}`, 'utf8');
+      const parsed = YAML.parse(file);
+      if (parsed?.openapi && parsed?.info?.version && parsed?.paths) {
+        this.oas.set(parsed.info.version, parsed);
+      }
+    }
+  }
+
+  private registerOperationsFromSpec(version: string, spec: OpenAPIV3.Document): void {
+    for (const path of Object.keys(spec.paths || {})) {
+      const operationConfigByMethod: Record<string, any> = spec.paths[path] ?? {};
+      for (const method of Object.keys(operationConfigByMethod)) {
+        const endPointConfig = operationConfigByMethod[method] as Record<string, any>;
+        if (endPointConfig?.operationId) {
+          this.registerOperationFromEndpoint({
+            version,
+            spec,
+            path,
+            endPointConfig
+          });
+        }
+      }
+    }
+  }
+
+  private registerOperationFromEndpoint({
+    version,
+    spec,
+    path,
+    endPointConfig
+  }: {
+    version: string;
+    spec: OpenAPIV3.Document;
+    path: string;
+    endPointConfig: Record<string, any>;
+  }): void {
+    const module = path.split('/')[1];
+    const {
+      moduleName,
+      controllerName
+    } = RealtimeAPIBase.resolveControllerMetadata(module);
+    const ControllerModule = RealtimeAPIBase.getControllerModule(
+      moduleName,
+      controllerName
+    );
+    const usersModuleComposition = moduleName === 'Users' ? this.composeUsersModule() : undefined;
+    const controller = new ControllerModule({
+      authService: usersModuleComposition?.authService ?? this.authService,
+      openApiSpecification: spec,
+      databaseClient: this.databaseClient,
+      userService: usersModuleComposition?.userService,
+      userUseCases: usersModuleComposition?.userUseCases,
+      organizationUseCases: usersModuleComposition?.organizationUseCases,
+      authUseCases: usersModuleComposition?.authUseCases,
+      mutexService: this.mutexClient,
+      passwordCryptoService: this.passwordCryptoService,
+      messageMediator: this.messageMediator
+    });
+
+    const operationId = endPointConfig.operationId as string;
+    const controllerMethod = OPERATION_TO_CONTROLLER_METHOD[operationId]
+      || operationId;
+    const runtimeHandler = this.getRuntimeHandlerFactory({
+      moduleName,
+      operationId,
+      controllerMethod,
+      controller,
+      endPointConfig
+    });
+    this.registerOperation({
+      version,
+      operationId,
+      moduleName,
+      endPointConfig,
+      controller,
+      controllerMethod,
+      runtimeHandler
+    });
+  }
+
+  private getRuntimeHandlerFactory({
+    moduleName,
+    operationId,
+    controllerMethod,
+    controller,
+    endPointConfig
+  }: {
+    moduleName: string;
+    operationId: string;
+    controllerMethod: string;
+    controller: Record<string, any>;
+    endPointConfig: Record<string, any>;
+  }): IRealtimeRuntimeHandler | undefined {
+    if (!this.interfaceType || !this.frameworkName) return undefined;
+    const handlerPath = `@src/modules/${moduleName}/interface/${this.interfaceType}/frameworks/${this.frameworkName}/handlers/${operationId}`;
+    try {
+      const handlerModule = require(handlerPath);
+      if (typeof handlerModule?.default !== 'function') return undefined;
+      return handlerModule.default({
+        operationId,
+        controllerMethod,
+        invoke: async (request: IAsyncOperationRequest): Promise<IAsyncOperationResponse> => {
+          const event = new RealtimeDomainEvent({
+            authorization: request.authorization || '',
+            input: request.input || {},
+            params: request.params || {},
+            queryString: request.queryString || {},
+            schemaOAS: endPointConfig,
+            entity: moduleName,
+            action: controllerMethod,
+            metadata: request.metadata
+          } as any);
+
+          const serviceResponse = await controller[controllerMethod](event);
+          if (serviceResponse?.error) {
+            throw serviceResponse.error;
+          }
+          return {
+            ok: true,
+            operationId,
+            metadata: request.metadata || {},
+            result: serviceResponse?.result
+          };
+        }
+      } as IRealtimeHandlerFactoryDeps);
+    } catch (error: any) {
+      const message = String(error?.message || '');
+      if (error?.code !== 'MODULE_NOT_FOUND' && !message.includes('Could not locate module')) {
+        throw error;
+      }
+    }
+    return undefined;
+  }
+
+  private static resolveControllerMetadata(
+    module: string
+  ): { moduleName: string; controllerName: string } {
+    if (module === 'auth') {
+      return { moduleName: 'Users', controllerName: 'AuthController' };
+    }
+    if (module === 'organizations') {
+      return { moduleName: 'Users', controllerName: 'OrganizationController' };
+    }
+    const moduleName = `${module.charAt(0).toUpperCase()}${module.substring(1, module.length)}`;
+    const singular = module.substring(1, module.length - 1);
+    const controllerName = `${module.charAt(0).toUpperCase()}${singular}Controller`;
+    return { moduleName, controllerName };
+  }
+
+  private static getControllerModule(moduleName: string, controllerName: string): any {
+    const controllerPath = `@src/modules/${moduleName}/adapters/in/http/controllers/${controllerName}`;
+    try {
+      const controllerModule = require(controllerPath)[controllerName];
+      if (controllerModule) return controllerModule;
+    } catch (error: any) {
+      const message = String(error?.message || '');
+      if (error?.code !== 'MODULE_NOT_FOUND' && !message.includes('Could not locate module')) {
+        throw error;
+      }
+    }
+
+    throw new Error(
+      `Controller ${controllerName} not found for module ${moduleName}.`
+    );
+  }
+}

package/templates/backend/src/interface/Async/RealtimeDomainEvent.ts

@@ -0,0 +1,3 @@
+import { BaseDomainEvent } from '@src/modules/port/BaseDomainEvent';
+
+export class RealtimeDomainEvent extends BaseDomainEvent {}

package/templates/backend/src/interface/CLI/core/catalogStorage.ts

@@ -0,0 +1,51 @@
+import fs from 'fs';
+import path from 'path';
+import type { IWorkspaceCatalog } from '@src/interface/CLI/types';
+
+/**
+ * Where the catalog lives, resolved per call rather than at import time.
+ *
+ * It used to be two module-level constants computed from `process.cwd()` when
+ * the module was first loaded. That fixes the catalog to whatever directory the
+ * process happened to start in: a CLI that changes directory, or that is
+ * imported before the target workspace is known, would read and write somewhere
+ * the user never chose — silently, since a missing file just yields the default
+ * catalog rather than an error.
+ *
+ * It also forced the tests to reload the module through `jest.resetModules()`
+ * after each `chdir`, which does not exist under Bun's runner (JUM-583). The
+ * lazy form is correct on its own terms and portable as a side effect.
+ */
+const catalogDir = (): string => path.resolve(process.cwd(), '.aaa-cli');
+const catalogFile = (): string => path.join(catalogDir(), 'workspace-catalog.json');
+
+const defaultCatalog = (): IWorkspaceCatalog => ({
+  version: 1,
+  domains: [],
+  entities: []
+});
+
+export const loadCatalog = async (): Promise<IWorkspaceCatalog> => {
+  const file = catalogFile();
+  if (!fs.existsSync(file)) {
+    return defaultCatalog();
+  }
+
+  const data = await fs.promises.readFile(file, 'utf8');
+  const parsed = JSON.parse(data) as IWorkspaceCatalog;
+  return {
+    version: parsed.version || 1,
+    domains: parsed.domains || [],
+    entities: parsed.entities || []
+  };
+};
+
+export const saveCatalog = async (catalog: IWorkspaceCatalog): Promise<void> => {
+  const dir = catalogDir();
+  if (!fs.existsSync(dir)) {
+    await fs.promises.mkdir(dir, { recursive: true });
+  }
+  await fs.promises.writeFile(catalogFile(), JSON.stringify(catalog, null, 2), 'utf8');
+};
+
+export const getCatalogFilePath = (): string => catalogFile();

package/templates/backend/src/interface/CLI/core/prompt.ts

@@ -0,0 +1,46 @@
+/* eslint-disable no-await-in-loop */
+/* eslint-disable no-constant-condition */
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+
+export class Prompt {
+  private readonly rl: readline.Interface;
+
+  constructor(
+    /* istanbul ignore next */
+    createInterface: () => readline.Interface = () => readline.createInterface({
+      input: input as unknown as NodeJS.ReadableStream,
+      output: output as unknown as NodeJS.WritableStream
+    })
+  ) {
+    this.rl = createInterface();
+  }
+
+  public async ask(question: string): Promise<string> {
+    const value = await this.rl.question(question);
+    return value.trim();
+  }
+
+  public async choose(title: string, options: string[]): Promise<number> {
+    // eslint-disable-next-line no-console
+    console.log(`\n${title}`);
+    options.forEach((option, index) => {
+      // eslint-disable-next-line no-console
+      console.log(` ${index + 1}. ${option}`);
+    });
+
+    while (true) {
+      const answer = await this.ask('Choose an option: ');
+      const selected = Number(answer);
+      if (Number.isInteger(selected) && selected >= 1 && selected <= options.length) {
+        return selected - 1;
+      }
+      // eslint-disable-next-line no-console
+      console.log('Invalid option. Please choose a valid number.');
+    }
+  }
+
+  public close(): void {
+    this.rl.close();
+  }
+}

package/templates/backend/src/interface/CLI/index.ts

@@ -0,0 +1,73 @@
+/* eslint-disable no-await-in-loop */
+/* eslint-disable no-constant-condition */
+/* eslint-disable no-continue */
+import { Prompt } from '@src/interface/CLI/core/prompt';
+import { getCatalogFilePath, loadCatalog, saveCatalog } from '@src/interface/CLI/core/catalogStorage';
+import type { ISubApplication, ISubApplicationContext } from '@src/interface/CLI/types';
+import { domainManagerSubApplication } from '@src/interface/CLI/subapps/domainManager';
+import { entityModelManagerSubApplication } from '@src/interface/CLI/subapps/entityModelManager';
+
+const subApplications: ISubApplication[] = [
+  domainManagerSubApplication,
+  entityModelManagerSubApplication
+];
+
+const buildContext = (prompt: Prompt): ISubApplicationContext => ({
+  ask: (question: string) => prompt.ask(question),
+  choose: (title: string, options: string[]) => prompt.choose(title, options),
+  log: (message: string) => {
+    // eslint-disable-next-line no-console
+    console.log(message);
+  },
+  loadCatalog,
+  saveCatalog
+});
+
+export const runCli = async (
+  prompt = new Prompt(),
+  registeredSubApplications: ISubApplication[] = subApplications
+): Promise<void> => {
+  const context = buildContext(prompt);
+
+  // eslint-disable-next-line no-console
+  console.log('\nAAA Development Automation CLI');
+  // eslint-disable-next-line no-console
+  console.log(`Catalog file: ${getCatalogFilePath()}`);
+
+  try {
+    while (true) {
+      const option = await context.choose('Main Menu', [
+        ...registeredSubApplications.map((item) => item.title),
+        'List registered sub applications',
+        'Exit'
+      ]);
+
+      if (option < registeredSubApplications.length) {
+        await registeredSubApplications[option].run(context);
+        continue;
+      }
+
+      if (option === registeredSubApplications.length) {
+        context.log('\nRegistered sub applications:');
+        registeredSubApplications.forEach((item, index) => {
+          context.log(` ${index + 1}. ${item.title} (${item.id})`);
+        });
+        continue;
+      }
+
+      context.log('Bye.');
+      return;
+    }
+  } finally {
+    prompt.close();
+  }
+};
+
+/* istanbul ignore next */
+if (require.main === module) {
+  runCli().catch((error: unknown) => {
+    // eslint-disable-next-line no-console
+    console.error('CLI execution failed:', error);
+    process.exitCode = 1;
+  });
+}