@koalarx/nest 3.1.50 → 4.0.2

package/cli/constants/auth-strategy-checklist.js

@@ -0,0 +1,314 @@
+import { AuthStrategy } from "./domain.js";
+import {
+  JWT_ONLY_REMOVE_PATHS,
+  OAUTH2_ONLY_REMOVE_PATHS
+} from "./auth-strategy-artifacts.js";
+export const AUTH_SHARED_REQUIRED_PATHS = [
+  "src/host/controllers/auth/auth.module.ts",
+  "src/host/security/security.module.ts",
+  "src/domain/auth/services/iauth.service.ts",
+  "src/infra/auth/jwt-token.service.ts",
+  "src/domain/dtos/logged-user-info.dto.ts",
+  "src/domain/entities/user/user.ts",
+  "src/infra/database/migrations/1781281330533-Init.ts"
+];
+export const JWT_REQUIRED_PATHS = [
+  "src/host/controllers/auth/login.controller.ts",
+  "src/application/auth/login/login.handler.ts",
+  "src/application/auth/refresh-token/refresh-token.handler.ts",
+  "src/test/application/login.handler.spec.ts"
+];
+export const OAUTH2_REQUIRED_PATHS = [
+  "src/application/auth/oauth2",
+  "src/host/controllers/oauth2/auth-link.controller.ts",
+  "src/application/auth/oauth2/auth-link/auth-link.handler.ts",
+  "src/host/decorators/scalar-token-endpoint.decorator.ts",
+  "src/domain/auth/dtos/oauth-user-info.dto.ts",
+  "src/domain/auth/dtos/auth-provider-config.dto.ts",
+  "src/infra/auth/oauth2-auth.service.ts",
+  "src/core/types/auth-provider-config-response.type.ts",
+  "src/core/auth/oauth-provider.registry.ts",
+  "src/core/auth/parse-oauth2-provider-env.ts",
+  "src/test/application/auth-link.handler.spec.ts",
+  "src/test/application/exchange-code.handler.spec.ts",
+  "src/test/application/scalar-oauth-token.handler.spec.ts",
+  "src/test/host/oauth-callback.controller.spec.ts",
+  "src/test/infra/oauth2-auth.service.spec.ts",
+  "src/test/core/oauth-provider.registry.spec.ts"
+];
+export const NO_AUTH_FORBIDDEN_PATHS = [
+  "src/application/auth",
+  "src/host/controllers/oauth2",
+  "src/host/security/security.module.ts",
+  "src/domain/auth",
+  "src/infra/auth",
+  "src/core/auth",
+  "src/domain/dtos/logged-user-info.dto.ts",
+  "src/domain/services/ilogged-user-info.service.ts",
+  "src/infra/services/logged-user-info.service.ts",
+  "src/host/decorators/scalar-token-endpoint.decorator.ts",
+  "src/host/decorators/restriction-by-profile.decorator.ts"
+];
+export const JWT_FORBIDDEN_CONTENT = [
+  "IOAuth2Service",
+  "OAuth2AuthService",
+  "OAuthProviderRegistry",
+  "OAuthUserInfoDto",
+  "AuthProviderConfigDto",
+  "parse-oauth2-provider-env",
+  "oauth-provider.registry",
+  "oauth2-auth.service",
+  "OAuthAuthLinkHandler",
+  "OAuthExchangeCodeController",
+  "ScalarOAuthTokenHandler",
+  "OAUTH2_PROVIDERS",
+  "OAUTH2_PROVIDER_ENV",
+  "parseOAuth2ProviderEnv"
+];
+export const OAUTH2_LOGIN_FORBIDDEN_CONTENT = [
+  "LoginController",
+  "LoginHandler"
+];
+export function resolveAuthProfile(selection) {
+  if (selection === false || selection.length === 0) {
+    return "none";
+  }
+  const hasJwt = selection.includes(AuthStrategy.JWT);
+  const hasOauth = selection.includes(AuthStrategy.OAUTH2);
+  if (hasJwt && hasOauth) {
+    return "jwt+oauth2";
+  }
+  if (hasJwt) {
+    return "jwt";
+  }
+  if (hasOauth) {
+    return "oauth2";
+  }
+  return "none";
+}
+export function requiredPathsForProfile(profile) {
+  switch (profile) {
+    case "none":
+      return [];
+    case "jwt":
+      return [...AUTH_SHARED_REQUIRED_PATHS, ...JWT_REQUIRED_PATHS];
+    case "oauth2":
+      return [...AUTH_SHARED_REQUIRED_PATHS, ...OAUTH2_REQUIRED_PATHS];
+    case "jwt+oauth2":
+      return [
+        ...AUTH_SHARED_REQUIRED_PATHS,
+        ...JWT_REQUIRED_PATHS,
+        ...OAUTH2_REQUIRED_PATHS
+      ];
+  }
+}
+export function forbiddenPathsForProfile(profile) {
+  switch (profile) {
+    case "none":
+      return NO_AUTH_FORBIDDEN_PATHS;
+    case "jwt":
+      return JWT_ONLY_REMOVE_PATHS;
+    case "oauth2":
+      return OAUTH2_ONLY_REMOVE_PATHS;
+    case "jwt+oauth2":
+      return [];
+  }
+}
+export function envExampleMustContain(profile) {
+  switch (profile) {
+    case "none":
+      return [];
+    case "jwt":
+      return ["JWT_PRIVATE_KEY"];
+    case "oauth2":
+      return ["JWT_PRIVATE_KEY", "OAUTH2_PROVIDERS"];
+    case "jwt+oauth2":
+      return ["JWT_PRIVATE_KEY", "OAUTH2_PROVIDERS"];
+  }
+}
+export function envExampleMustNotContain(profile) {
+  switch (profile) {
+    case "none":
+      return ["JWT_PRIVATE_KEY", "OAUTH2_PROVIDERS"];
+    case "jwt":
+      return ["OAUTH2_PROVIDERS"];
+    case "oauth2":
+      return [];
+    case "jwt+oauth2":
+      return [];
+  }
+}
+export function envSourceMustContain(profile) {
+  switch (profile) {
+    case "none":
+      return [];
+    case "jwt":
+      return ["JWT_PRIVATE_KEY"];
+    case "oauth2":
+      return ["OAUTH2_PROVIDERS", "parse-oauth2-provider-env"];
+    case "jwt+oauth2":
+      return ["JWT_PRIVATE_KEY", "OAUTH2_PROVIDERS", "parse-oauth2-provider-env"];
+  }
+}
+export function envSourceMustNotContain(profile) {
+  switch (profile) {
+    case "none":
+      return [
+        "JWT_PRIVATE_KEY",
+        "OAUTH2_PROVIDERS",
+        "parse-oauth2-provider-env",
+        "OAUTH2_PROVIDER_ENV"
+      ];
+    case "jwt":
+      return ["parse-oauth2-provider-env", "OAUTH2_PROVIDERS", "OAUTH2_PROVIDER_ENV"];
+    case "oauth2":
+      return [];
+    case "jwt+oauth2":
+      return [];
+  }
+}
+export function iauthMustContain(profile) {
+  switch (profile) {
+    case "none":
+      return [];
+    case "jwt":
+      return ["IJwtTokenService"];
+    case "oauth2":
+      return ["IJwtTokenService", "IOAuth2Service"];
+    case "jwt+oauth2":
+      return ["IJwtTokenService", "IOAuth2Service"];
+  }
+}
+export function iauthMustNotContain(profile) {
+  switch (profile) {
+    case "none":
+      return ["IJwtTokenService", "IOAuth2Service"];
+    case "jwt":
+      return ["IOAuth2Service"];
+    case "oauth2":
+      return [];
+    case "jwt+oauth2":
+      return [];
+  }
+}
+export function authModuleMustContain(profile) {
+  switch (profile) {
+    case "none":
+      return [];
+    case "jwt":
+      return ["LoginController"];
+    case "oauth2":
+      return ["OAuthAuthLinkController"];
+    case "jwt+oauth2":
+      return ["LoginController", "OAuthAuthLinkController"];
+  }
+}
+export function authModuleMustNotContain(profile) {
+  switch (profile) {
+    case "none":
+      return ["LoginController", "OAuthAuthLinkController"];
+    case "jwt":
+      return ["OAuthAuthLinkController"];
+    case "oauth2":
+      return ["LoginController"];
+    case "jwt+oauth2":
+      return [];
+  }
+}
+export function securityModuleMustContain(profile) {
+  switch (profile) {
+    case "none":
+      return [];
+    case "jwt":
+      return ["IJwtTokenService"];
+    case "oauth2":
+      return ["IJwtTokenService", "IOAuth2Service", "OAuthProviderRegistry"];
+    case "jwt+oauth2":
+      return ["IJwtTokenService", "IOAuth2Service", "OAuthProviderRegistry"];
+  }
+}
+export function securityModuleMustNotContain(profile) {
+  switch (profile) {
+    case "none":
+      return ["SecurityModule", "IJwtTokenService", "IOAuth2Service"];
+    case "jwt":
+      return ["IOAuth2Service", "OAuthProviderRegistry"];
+    case "oauth2":
+      return [];
+    case "jwt+oauth2":
+      return [];
+  }
+}
+export function cacheConstantsMustContain(profile) {
+  return profile === "oauth2" || profile === "jwt+oauth2" ? ["OAUTH2_STATE"] : [];
+}
+export function cacheConstantsMustNotContain(profile) {
+  return profile === "jwt" || profile === "none" ? ["OAUTH2_STATE"] : [];
+}
+export function defineDocumentationMustContain(profile) {
+  switch (profile) {
+    case "none":
+      return ["apiReference"];
+    case "jwt":
+      return ["JWT", "isProviderRegistered"];
+    case "oauth2":
+      return ["buildDocAuthorizations", "IOAuth2Service"];
+    case "jwt+oauth2":
+      return ["JWT", "IOAuth2Service", "buildDocAuthorizations"];
+  }
+}
+export function defineDocumentationMustNotContain(profile) {
+  switch (profile) {
+    case "none":
+      return ["buildDocAuthorizations", "IOAuth2Service", "OAuthProviderRegistry"];
+    case "jwt":
+      return ["OAuthProviderRegistry", "IOAuth2Service"];
+    case "oauth2":
+      return [];
+    case "jwt+oauth2":
+      return [];
+  }
+}
+export function appModuleMustContain(profile) {
+  switch (profile) {
+    case "none":
+      return ["InfraModule"];
+    case "jwt":
+    case "oauth2":
+    case "jwt+oauth2":
+      return ["SecurityModule", "AuthModule"];
+  }
+}
+export function appModuleMustNotContain(profile) {
+  return profile === "none" ? ["SecurityModule", "AuthModule"] : [];
+}
+export function forbiddenContentPatterns(profile) {
+  switch (profile) {
+    case "none":
+      return [...JWT_FORBIDDEN_CONTENT, ...OAUTH2_LOGIN_FORBIDDEN_CONTENT];
+    case "jwt":
+      return JWT_FORBIDDEN_CONTENT;
+    case "oauth2":
+      return OAUTH2_LOGIN_FORBIDDEN_CONTENT;
+    case "jwt+oauth2":
+      return [];
+  }
+}
+export const AUTH_PROFILE_MATRIX = [
+  "none",
+  "jwt",
+  "oauth2",
+  "jwt+oauth2"
+];
+export function profileToAuthStrategies(profile) {
+  switch (profile) {
+    case "none":
+      return false;
+    case "jwt":
+      return [AuthStrategy.JWT];
+    case "oauth2":
+      return [AuthStrategy.OAUTH2];
+    case "jwt+oauth2":
+      return [AuthStrategy.JWT, AuthStrategy.OAUTH2];
+  }
+}

package/cli/constants/cli-commands.js

@@ -0,0 +1,24 @@
+export const CliCommand = {
+  HELP: "help",
+  NEW: "new",
+  ADD: "add",
+  VERSION: "version"
+};
+export const CliFlag = {
+  HELP: "--help",
+  HELP_SHORT: "-h",
+  VERBOSE: "--verbose",
+  NEW: "--new",
+  NEW_SHORT: "-n",
+  ADD: "--add",
+  ADD_SHORT: "-a",
+  VERSION: "--version",
+  VERSION_SHORT: "-v",
+  TEMPLATE: "--template",
+  TEMPLATE_SHORT: "-t",
+  PACKAGE_MANAGER: "--package-manager",
+  PACKAGE_MANAGER_SHORT: "--pm",
+  AUTH: "--auth",
+  FEATURES: "--features",
+  FEATURE: "--feature"
+};

package/cli/constants/cli-project-checklist.js

@@ -0,0 +1,289 @@
+import {
+  AuthStrategy,
+  ExtraFeature,
+  Template,
+  resolveNewProjectOptions
+} from "./domain.js";
+import { resolveProjectFeatures } from "../utils/install-module.js";
+export const CORE_REQUIRED_PATHS = [
+  "src/core/env.ts",
+  "src/host/main.ts",
+  "src/host/app.module.ts",
+  "src/host/jobs/jobs.module.ts",
+  "src/host/jobs/jobs-bootstrap.service.ts",
+  "src/infra/infra.module.ts",
+  "src/host/open-api/define-documentation.ts",
+  "src/infra/repositories/repository.module.ts",
+  "src/infra/database/data-source-factory.ts"
+];
+export const CORE_PACKAGE_DEPENDENCIES = [
+  "@koalarx/utils",
+  "zod",
+  "typeorm",
+  "@scalar/nestjs-api-reference"
+];
+export const DEFAULT_TEMPLATE_FORBIDDEN_PATHS = [
+  "src/host/controllers/person/person.module.ts",
+  "src/infra/repositories/person.repository.ts"
+];
+export const CRUD_TEMPLATE_REQUIRED_PATHS = [
+  "src/host/controllers/person/person.module.ts",
+  "src/host/controllers/person/delete-person.controller.ts",
+  "src/application/person/jobs/cron/create-person.job.ts",
+  "src/application/person/jobs/cron/delete-inactive.job.ts",
+  "src/application/person/jobs/events/person/person-event.job.ts",
+  "src/application/person/jobs/events/person/inactive-person/inactive-person.handler.ts",
+  "src/application/person/jobs/events/person/inactive-person/inactive-person.event.ts"
+];
+export const CRUD_TEMPLATE_FORBIDDEN_PATHS = [
+  "src/application/person/events"
+];
+export const CRUD_BUNDLED_PACKAGES = [
+  "ioredis",
+  "cron-parser"
+];
+export const CACHE_REDIS_REQUIRED_PATHS = [
+  "src/infra/common/redis-cache.service.ts"
+];
+export const CACHE_REDIS_PACKAGES = ["ioredis"];
+export const HEALTH_REQUIRED_PATHS = [
+  "src/host/controllers/health-check/health-check.controller.ts",
+  "src/infra/services/database.indicator.service.ts"
+];
+export const HEALTH_REDIS_INDICATOR_PATH = "src/infra/services/redis.indicator.service.ts";
+export const HEALTH_PACKAGES = ["@nestjs/terminus", "@nestjs/axios"];
+export const CRON_REQUIRED_PATHS = [
+  "src/core/utils/cron-expression-to-boolean.ts",
+  "src/core/background-services/cron-service/cron-job.handler.base.ts"
+];
+export const CRON_PACKAGES = ["cron-parser"];
+export const EVENTS_REQUIRED_PATHS = [
+  "src/core/background-services/event-service/event-handler.base.ts"
+];
+export const AUTH_JWT_PACKAGES = ["@nestjs/jwt", "passport-jwt"];
+export const CLI_NEW_SELECTION_MATRIX = [
+  {
+    label: "default sem auth",
+    template: Template.DEFAULT,
+    auth: [],
+    features: []
+  },
+  {
+    label: "default sem auth + health",
+    template: Template.DEFAULT,
+    auth: [],
+    features: [ExtraFeature.HEALTH_CHECK]
+  },
+  {
+    label: "default sem auth + cache",
+    template: Template.DEFAULT,
+    auth: [],
+    features: [ExtraFeature.CACHE]
+  },
+  {
+    label: "default sem auth + cron",
+    template: Template.DEFAULT,
+    auth: [],
+    features: [ExtraFeature.INTERNAL_CRON_JOBS]
+  },
+  {
+    label: "default sem auth + events",
+    template: Template.DEFAULT,
+    auth: [],
+    features: [ExtraFeature.INTERNAL_EVENT_JOBS]
+  },
+  {
+    label: "default sem auth + cache + health + cron + events",
+    template: Template.DEFAULT,
+    auth: [],
+    features: [
+      ExtraFeature.CACHE,
+      ExtraFeature.HEALTH_CHECK,
+      ExtraFeature.INTERNAL_CRON_JOBS,
+      ExtraFeature.INTERNAL_EVENT_JOBS
+    ]
+  },
+  {
+    label: "default jwt",
+    template: Template.DEFAULT,
+    auth: [AuthStrategy.JWT],
+    features: []
+  },
+  {
+    label: "default oauth2",
+    template: Template.DEFAULT,
+    auth: [AuthStrategy.OAUTH2],
+    features: []
+  },
+  {
+    label: "default jwt + oauth2",
+    template: Template.DEFAULT,
+    auth: [AuthStrategy.JWT, AuthStrategy.OAUTH2],
+    features: []
+  },
+  {
+    label: "default jwt + cache + health",
+    template: Template.DEFAULT,
+    auth: [AuthStrategy.JWT],
+    features: [ExtraFeature.CACHE, ExtraFeature.HEALTH_CHECK]
+  },
+  {
+    label: "crud jwt",
+    template: Template.CRUD_SAMPLE,
+    auth: [AuthStrategy.JWT],
+    features: []
+  },
+  {
+    label: "crud oauth2",
+    template: Template.CRUD_SAMPLE,
+    auth: [AuthStrategy.OAUTH2],
+    features: []
+  },
+  {
+    label: "crud jwt + oauth2",
+    template: Template.CRUD_SAMPLE,
+    auth: [AuthStrategy.JWT, AuthStrategy.OAUTH2],
+    features: []
+  }
+];
+export function buildProjectExpectation(template, auth, features) {
+  const resolved = resolveNewProjectOptions(template, [...auth], [...features]);
+  const projectFeatures = resolveProjectFeatures(resolved.features, resolved.auth);
+  let cache = false;
+  if (projectFeatures.cacheWithRedis) {
+    cache = "redis";
+  } else if (projectFeatures.cache) {
+    cache = "memory";
+  }
+  return {
+    template,
+    auth: resolved.auth.length === 0 ? false : resolved.auth,
+    cache,
+    health: projectFeatures.health,
+    cronJobs: projectFeatures.cronJobs,
+    eventJobs: projectFeatures.eventJobs
+  };
+}
+export function requiredPathsForExpectation(expectation) {
+  const paths = [...CORE_REQUIRED_PATHS];
+  if (expectation.template === Template.CRUD_SAMPLE) {
+    paths.push(...CRUD_TEMPLATE_REQUIRED_PATHS);
+  }
+  if (expectation.cache === "redis") {
+    paths.push(...CACHE_REDIS_REQUIRED_PATHS);
+  }
+  if (expectation.health) {
+    paths.push(...HEALTH_REQUIRED_PATHS);
+    if (expectation.cache === "redis") {
+      paths.push(HEALTH_REDIS_INDICATOR_PATH);
+    }
+  }
+  if (expectation.cronJobs) {
+    paths.push(...CRON_REQUIRED_PATHS);
+  }
+  if (expectation.eventJobs) {
+    paths.push(...EVENTS_REQUIRED_PATHS);
+  }
+  return paths;
+}
+export function forbiddenPathsForExpectation(expectation) {
+  const paths = [];
+  if (expectation.template === Template.DEFAULT) {
+    paths.push(...DEFAULT_TEMPLATE_FORBIDDEN_PATHS);
+  } else {
+    paths.push(...CRUD_TEMPLATE_FORBIDDEN_PATHS);
+  }
+  if (expectation.cache !== "redis") {
+    paths.push(...CACHE_REDIS_REQUIRED_PATHS);
+  }
+  if (!expectation.health) {
+    paths.push(...HEALTH_REQUIRED_PATHS, HEALTH_REDIS_INDICATOR_PATH);
+  } else if (expectation.cache !== "redis") {
+    paths.push(HEALTH_REDIS_INDICATOR_PATH);
+  }
+  if (!expectation.cronJobs) {
+    paths.push(...CRON_REQUIRED_PATHS);
+  }
+  if (!expectation.eventJobs) {
+    paths.push(...EVENTS_REQUIRED_PATHS);
+  }
+  return paths;
+}
+export function requiredPackagesForExpectation(expectation) {
+  const packages = new Set(CORE_PACKAGE_DEPENDENCIES);
+  if (expectation.cache === "redis") {
+    for (const pkg of CACHE_REDIS_PACKAGES) {
+      packages.add(pkg);
+    }
+  }
+  if (expectation.health) {
+    for (const pkg of HEALTH_PACKAGES) {
+      packages.add(pkg);
+    }
+  }
+  if (expectation.cronJobs) {
+    for (const pkg of CRON_PACKAGES) {
+      packages.add(pkg);
+    }
+  }
+  if (expectation.auth !== false) {
+    for (const pkg of AUTH_JWT_PACKAGES) {
+      packages.add(pkg);
+    }
+  }
+  return [...packages];
+}
+export function appModuleMustContain(expectation) {
+  const patterns = ["JobsModule.register"];
+  if (expectation.template === Template.CRUD_SAMPLE) {
+    patterns.push("PersonModule", "InactivePersonHandler", "CreatePersonJob", "DeleteInactiveJob");
+  } else if (expectation.auth === false) {
+    patterns.push("InfraModule", "eventHandlers: []", "cronJobs: []");
+  } else {
+    patterns.push("eventHandlers: []", "cronJobs: []");
+  }
+  if (expectation.health) {
+    patterns.push("HealthCheckModule");
+  }
+  if (expectation.auth !== false) {
+    patterns.push("SecurityModule", "AuthModule");
+  }
+  return patterns;
+}
+export function appModuleMustNotContain(expectation) {
+  const patterns = [];
+  if (expectation.template === Template.DEFAULT) {
+    patterns.push("PersonModule");
+  }
+  if (expectation.auth === false) {
+    patterns.push("SecurityModule", "AuthModule");
+  }
+  if (!expectation.health) {
+    patterns.push("HealthCheckModule");
+  }
+  return patterns;
+}
+export function infraModuleMustContain(expectation) {
+  if (expectation.cache === false) {
+    return [];
+  }
+  return ["ICacheService", "CacheServiceProvider"];
+}
+export function infraModuleMustNotContain(expectation) {
+  if (expectation.cache === false) {
+    return ["ICacheService", "CacheServiceProvider"];
+  }
+  return [];
+}
+export function healthControllerMustContain(expectation) {
+  if (!expectation.health) {
+    return [];
+  }
+  return expectation.cache === "redis" ? ["RedisIndicator"] : [];
+}
+export function healthControllerMustNotContain(expectation) {
+  if (!expectation.health || expectation.cache === "redis") {
+    return [];
+  }
+  return ["RedisIndicator"];
+}

package/cli/constants/core-packages.js

@@ -0,0 +1,34 @@
+export const CORE_PACKAGES = [
+  "@koalarx/utils",
+  "@nestjs/config",
+  "@nestjs/swagger",
+  "typeorm",
+  "pg",
+  "zod",
+  "@scalar/nestjs-api-reference"
+];
+export const CACHE_PACKAGES = ["ioredis"];
+export const AUTH_PACKAGES = [
+  "@nestjs/jwt",
+  "@nestjs/passport",
+  "passport",
+  "passport-jwt",
+  "cookie-parser",
+  "bcrypt"
+];
+export const AUTH_DEV_PACKAGES = [
+  "@types/cookie-parser",
+  "@types/bcrypt"
+];
+export const CRON_PACKAGES = ["cron-parser"];
+export const HEALTH_PACKAGES = ["@nestjs/terminus", "@nestjs/axios"];
+export function devAddFlag(packageManager) {
+  switch (packageManager) {
+    case "npm":
+      return "-D";
+    case "pnpm":
+      return "-D";
+    default:
+      return "-d";
+  }
+}