@expressots/cli 3.0.0 → 4.0.0-preview.3

package/bin/generate/templates/nonopinionated/guard.tpl

@@ -0,0 +1,18 @@
+import { provide } from "@expressots/core";
+import { Request, Response, NextFunction } from "express";
+
+@provide({{className}}Guard)
+export class {{className}}Guard {
+    canActivate(req: Request, res: Response, next: NextFunction): void {
+        const authHeader = req.headers.authorization;
+
+        if (!authHeader) {
+            res.status(401).json({ message: "Unauthorized" });
+            return;
+        }
+
+        // TODO: Validate token
+        next();
+    }
+}
+

package/bin/generate/templates/nonopinionated/handler.tpl

@@ -0,0 +1,12 @@
+import { provide, OnEvent, IEventHandler } from "@expressots/core";
+import { {{{eventName}}} } from "{{{eventPath}}}";
+
+@provide({{className}}Handler)
+@OnEvent({{eventName}}, { priority: {{priority}} })
+export class {{className}}Handler implements IEventHandler<{{eventName}}> {
+    async handle(event: {{eventName}}): Promise<void> {
+        // TODO: Implement handler logic
+        console.log(`Handling ${event.constructor.name}`);
+    }
+}
+

package/bin/generate/templates/nonopinionated/interceptor.tpl

@@ -0,0 +1,27 @@
+import {
+    IInterceptor,
+    ExecutionContext,
+    CallHandler,
+    Interceptor,
+    provide,
+} from "@expressots/core";
+
+@Interceptor({ priority: {{priority}} })
+@provide({{className}}Interceptor)
+export class {{className}}Interceptor implements IInterceptor {
+    async intercept(context: ExecutionContext, next: CallHandler) {
+        const request = context.getRequest();
+
+        // Pre-processing
+        const startTime = Date.now();
+
+        const result = await next.handle();
+
+        // Post-processing
+        const duration = Date.now() - startTime;
+        console.log(`[{{className}}] ${request.method} ${request.path} - ${duration}ms`);
+
+        return result;
+    }
+}
+

package/bin/generate/templates/opinionated/config.tpl

@@ -0,0 +1,47 @@
+import { defineConfig, Env, loadEnvSync } from "@expressots/core";
+
+/**
+ * {{className}} Configuration
+ *
+ * Type-safe configuration with full TypeScript inference.
+ * Features:
+ * - Multi-environment defaults
+ * - Secret management with auto-redaction
+ * - Validation with helpful errors
+ */
+
+// Load environment files before config resolution
+const envFiles = {
+    development: ".env.local",
+    production: ".env.prod",
+};
+
+loadEnvSync({ files: envFiles });
+
+export const {{moduleName}}Config = defineConfig({
+    // Add your configuration schema here
+    enabled: Env.boolean("{{envPrefix}}_ENABLED", {
+        default: true,
+        description: "Enable/disable {{className}} feature",
+    }),
+    // Example settings - customize as needed
+    setting1: Env.string("{{envPrefix}}_SETTING1", {
+        default: "default-value",
+    }),
+    setting2: Env.number("{{envPrefix}}_SETTING2", {
+        default: 100,
+        min: 0,
+        max: 1000,
+    }),
+    bootstrap: {
+        envFileConfig: {
+            autoCreateTemplate: true,
+            files: envFiles,
+        },
+    },
+});
+
+// Export typed config values
+export const config = {{moduleName}}Config.values;
+export type {{className}}Config = typeof config;
+

package/bin/generate/templates/opinionated/entity.tpl

@@ -1,11 +1,4 @@
 import { provide } from "@expressots/core";
-import { randomUUID } from "node:crypto";
 
 @provide({{className}}Entity)
-export class {{className}}Entity {
-    id: string;
-
-    constructor() {
-        this.id = randomUUID();
-    }
-}
+export class {{className}}Entity {}

package/bin/generate/templates/opinionated/event.tpl

@@ -0,0 +1,15 @@
+/**
+ * {{className}} Event
+ *
+ * Type-safe event - no strings!
+ *
+ * Usage:
+ * await this.eventEmitter.emit(new {{className}}Event(data));
+ */
+export class {{className}}Event {
+    constructor(
+        public readonly data: Record<string, unknown>,
+        public readonly timestamp: Date = new Date(),
+    ) {}
+}
+

package/bin/generate/templates/opinionated/guard.tpl

@@ -0,0 +1,41 @@
+import { provide } from "@expressots/core";
+import { Request, Response, NextFunction } from "express";
+
+/**
+ * {{className}} Guard
+ *
+ * Usage:
+ * @controller("/protected")
+ * @Use({{className}}Guard)
+ * export class ProtectedController { }
+ */
+@provide({{className}}Guard)
+export class {{className}}Guard {
+    /**
+     * Check if the request is authorized
+     */
+    canActivate(req: Request, res: Response, next: NextFunction): void {
+        // TODO: Implement authorization logic
+        const isAuthorized = this.checkAuthorization(req);
+
+        if (!isAuthorized) {
+            res.status(401).json({ message: "Unauthorized" });
+            return;
+        }
+
+        next();
+    }
+
+    private checkAuthorization(req: Request): boolean {
+        // Example: Check for authorization header
+        const authHeader = req.headers.authorization;
+
+        if (!authHeader) {
+            return false;
+        }
+
+        // TODO: Validate token/credentials
+        return true;
+    }
+}
+

package/bin/generate/templates/opinionated/handler.tpl

@@ -0,0 +1,23 @@
+import { provide, OnEvent, IEventHandler } from "@expressots/core";
+import { {{{eventName}}} } from "{{{eventPath}}}";
+
+/**
+ * Handler for {{eventName}}
+ *
+ * Features:
+ * - Auto-discovered
+ * - Priority: {{priority}}
+ * - Full type safety
+ */
+@provide({{className}}Handler)
+@OnEvent({{eventName}}, { priority: {{priority}} })
+export class {{className}}Handler implements IEventHandler<{{eventName}}> {
+    async handle(event: {{eventName}}): Promise<void> {
+        console.log(`Handling ${event.constructor.name}`, {
+            timestamp: event.timestamp,
+        });
+
+        // TODO: Implement handler logic
+    }
+}
+

package/bin/generate/templates/opinionated/interceptor.tpl

@@ -0,0 +1,50 @@
+import {
+    IInterceptor,
+    ExecutionContext,
+    CallHandler,
+    Interceptor,
+    provide,
+} from "@expressots/core";
+
+/**
+ * {{className}} Interceptor
+ *
+ * Priority: {{priority}} (lower = earlier execution)
+ *
+ * Usage:
+ * @UseInterceptors({{className}}Interceptor)
+ * @controller("/route")
+ * export class MyController { }
+ */
+@Interceptor({ priority: {{priority}} })
+@provide({{className}}Interceptor)
+export class {{className}}Interceptor implements IInterceptor {
+    async intercept(context: ExecutionContext, next: CallHandler) {
+        const request = context.getRequest();
+
+        // Pre-processing logic
+        console.log(`[{{className}}] Before handler`, {
+            method: request.method,
+            path: request.path,
+        });
+
+        const startTime = Date.now();
+
+        try {
+            // Execute next interceptor or handler
+            const result = await next.handle();
+
+            // Post-processing logic
+            const duration = Date.now() - startTime;
+            console.log(`[{{className}}] After handler`, {
+                duration: `${duration}ms`,
+            });
+
+            return result;
+        } catch (error) {
+            console.error(`[{{className}}] Handler error`, error);
+            throw error;
+        }
+    }
+}
+

package/bin/generate/utils/command-utils.d.ts

@@ -69,9 +69,10 @@ export declare function getFileNameWithoutExtension(filePath: string): string;
  * @param schematic
  * @returns the split target
  */
-export declare const splitTarget: ({ target, schematic, }: {
+export declare const splitTarget: ({ target, schematic, opinionated, }: {
     target: string;
     schematic: string;
+    opinionated?: boolean;
 }) => Promise<{
     path: string;
     file: string;
@@ -99,10 +100,14 @@ export declare const writeTemplate: ({ outputPath, template: { path, data }, }:
     };
 }) => void;
 /**
- * Returns the folder where the schematic should be placed
- * @param schematic
+ * Returns the folder where the schematic should be placed.
+ * Uses scaffoldSchematics from config if defined, otherwise falls back to defaults.
+ *
+ * @param schematic - The schematic type (usecase, controller, etc.)
+ * @param scaffoldSchematics - Custom folder mappings from expressots.config.ts
+ * @returns The folder path for the schematic
  */
-export declare const schematicFolder: (schematic: string) => string | undefined;
+export declare const schematicFolder: (schematic: string, scaffoldSchematics?: ExpressoConfig["scaffoldSchematics"]) => string | undefined;
 /**
  * Get the name with the scaffold pattern
  * @param name
@@ -116,7 +121,17 @@ export declare const getNameWithScaffoldPattern: (name: string) => Promise<strin
  */
 export declare function extractFirstWord(file: string): Promise<string>;
 /**
- * Check if the path is a nested path, a single path or a sugar path
+ * Determine the path style for a generate target.
+ *
+ * - `Nested`: contains an explicit separator (`billing/invoice`) → grouped
+ *   under the parent folder.
+ * - `Sugar`: a single segment that normalizes to more than one word
+ *   (`userCreate`, `user-create`, `user_create`, `UserCreate`) → grouped under
+ *   its first word as a shared module (e.g. `UserModule`). camelCase and
+ *   kebab-case forms of the same name therefore produce identical output.
+ * - `Single`: a true single-word target (`user`) → self-contained module in its
+ *   own folder.
+ *
  * @param path
  * @returns the path style
  */

package/bin/generate/utils/command-utils.js

@@ -34,6 +34,35 @@ const string_utils_1 = require("./string-utils");
 const cli_ui_1 = require("../../utils/cli-ui");
 const verify_file_exists_1 = require("../../utils/verify-file-exists");
 const compiler_1 = __importDefault(require("../../utils/compiler"));
+const update_tsconfig_paths_1 = require("../../utils/update-tsconfig-paths");
+const input_validation_1 = require("../../utils/input-validation");
+const shared_1 = require("@expressots/shared");
+/**
+ * Reject generate targets that would resolve outside the project's
+ * source root. We only inspect the user-supplied `rawTarget` for
+ * absolute-path escape (`/etc/...`, `C:\Windows\...`); the
+ * `relativePath` is built internally and may legitimately start with
+ * a leading `/` when the schematic doesn't introduce its own folder.
+ *
+ * Aborts via `process.exit(1)` after `printError` so the caller
+ * surfaces a friendly message and writes nothing.
+ */
+function ensureWithinSourceRoot(folderToScaffold, relativePath, rawTarget) {
+    if (nodePath.isAbsolute(rawTarget)) {
+        (0, cli_ui_1.printError)("Absolute paths are not allowed for generate targets", rawTarget);
+        process.exit(1);
+    }
+    // Strip leading slashes from the synthesized relative path before
+    // resolution; the leading slash is a benign artifact of empty
+    // `path` segments, not an escape attempt.
+    const stripped = relativePath.replace(/^[\\/]+/, "");
+    const baseAbs = nodePath.resolve(process.cwd(), folderToScaffold);
+    const safe = (0, input_validation_1.safeResolveWithin)(baseAbs, stripped);
+    if (safe === null) {
+        (0, cli_ui_1.printError)(`Path traversal detected. Targets must stay inside ${folderToScaffold}`, rawTarget);
+        process.exit(1);
+    }
+}
 /**
  * Create a template based on the schematic
  * @param fp
@@ -46,15 +75,21 @@ async function validateAndPrepareFile(fp) {
         process.exit(1);
     }
     if (opinionated) {
-        const folderSchematic = (0, exports.schematicFolder)(fp.schematic);
+        const folderSchematic = (0, exports.schematicFolder)(fp.schematic, scaffoldSchematics);
         const folderToScaffold = `${sourceRoot}/${folderSchematic}`;
         const { path, file, className, moduleName, modulePath } = await (0, exports.splitTarget)({
             target: fp.target,
             schematic: fp.schematic,
+            opinionated: true,
         });
+        ensureWithinSourceRoot(folderToScaffold, `${path}/${file}`, fp.target);
         const outputPath = `${folderToScaffold}/${path}/${file}`;
         await (0, verify_file_exists_1.verifyIfFileExists)(outputPath, fp.schematic);
         (0, node_fs_1.mkdirSync)(`${folderToScaffold}/${path}`, { recursive: true });
+        // Update tsconfig paths dynamically (handles both default and custom folder names)
+        if (folderSchematic) {
+            await (0, update_tsconfig_paths_1.updateTsconfigPaths)(folderSchematic, sourceRoot);
+        }
         return {
             path,
             file,
@@ -77,6 +112,7 @@ async function validateAndPrepareFile(fp) {
     const validateFileSchema = fileBaseSchema !== undefined
         ? file.replace(fp.schematic, fileBaseSchema)
         : file;
+    ensureWithinSourceRoot(folderToScaffold, `${path}/${validateFileSchema}`, fp.target);
     const outputPath = `${folderToScaffold}/${path}/${validateFileSchema}`;
     await (0, verify_file_exists_1.verifyIfFileExists)(outputPath, fp.schematic);
     (0, node_fs_1.mkdirSync)(`${folderToScaffold}/${path}`, { recursive: true });
@@ -108,7 +144,7 @@ exports.getFileNameWithoutExtension = getFileNameWithoutExtension;
  * @param schematic
  * @returns the split target
  */
-const splitTarget = async ({ target, schematic, }) => {
+const splitTarget = async ({ target, schematic, opinionated = false, }) => {
     const pathContent = target
         .split("/")
         .filter((item) => item !== "");
@@ -158,28 +194,69 @@ const splitTarget = async ({ target, schematic, }) => {
             schematic = "controller";
         // 1. Extract the name (first part of the target)
         const [name, ...remainingPath] = target.split("/");
-        // 2. Check if the name is camelCase or kebab-case
+        // 2. Check if the name is camelCase or kebab-case (compound word)
         const camelCaseRegex = /[A-Z]/;
         const kebabCaseRegex = /[_\-\s]+/;
         const isCamelCase = camelCaseRegex.test(name);
         const isKebabCase = kebabCaseRegex.test(name);
+        // Schematics that should create their own subfolder (grouped resources)
+        const groupedSchematics = [
+            "usecase",
+            "controller",
+            "service",
+            "dto",
+            "module",
+        ];
+        const shouldCreateFolder = groupedSchematics.includes(schematic);
         if (isCamelCase || isKebabCase) {
-            const [wordName, ...path] = name
-                ? name
-                    .split(isCamelCase ? /(?=[A-Z])/ : kebabCaseRegex)
-                    .map((word) => word.toLowerCase())
-                : [];
+            // Convert compound name to kebab-case for folder path (e.g., confirmLogin -> confirm-login)
+            const folderName = (0, string_utils_1.anyCaseToKebabCase)(name);
+            // Extract first word for module name
+            const firstWord = name
+                .split(isCamelCase ? /(?=[A-Z])/ : kebabCaseRegex)[0]
+                .toLowerCase();
+            // Opinionated "syntactic sugar": decompose a compound name into a
+            // nested feature/use-case layout so every use-case of a feature is
+            // grouped under one module at the feature root. For example
+            // `userLogin` -> `user/login/login.{controller,usecase,dto}.ts` with
+            // the shared module at `user/user.module.ts`. A later `userLogout`
+            // adds `user/logout/...` and joins the same `UserModule`.
+            //
+            // Only applies to grouped schematics in opinionated mode; standalone
+            // schematics and non-opinionated mode keep the flat kebab folder so
+            // the developer retains full control over structure.
+            if (opinionated && shouldCreateFolder) {
+                const words = folderName.split("-").filter(Boolean);
+                if (words.length > 1) {
+                    const feature = words[0];
+                    const useCase = words.slice(1).join("-");
+                    return {
+                        path: `${feature}/${useCase}`,
+                        file: `${await (0, exports.getNameWithScaffoldPattern)(useCase)}.${schematic}.ts`,
+                        className: (0, string_utils_1.anyCaseToPascalCase)(useCase),
+                        moduleName: feature,
+                        modulePath: feature,
+                    };
+                }
+            }
+            // For standalone schematics (entity, provider, middleware, etc.),
+            // only create folder if explicit path is provided
+            const computedPath = shouldCreateFolder
+                ? `${folderName}${pathEdgeCase(remainingPath)}`
+                : remainingPath.length > 0
+                    ? `${folderName}${pathEdgeCase(remainingPath)}`
+                    : "";
             return {
-                path: `${wordName}/${pathEdgeCase(path)}${pathEdgeCase(remainingPath)}`,
+                path: computedPath,
                 file: `${await (0, exports.getNameWithScaffoldPattern)(name)}.${schematic}.ts`,
                 className: (0, string_utils_1.anyCaseToPascalCase)(name),
-                moduleName: wordName,
+                moduleName: firstWord,
                 modulePath: pathContent[0].split("-")[1],
             };
         }
         // 3. Return the base case
         return {
-            path: "",
+            path: shouldCreateFolder ? name : "",
             file: `${await (0, exports.getNameWithScaffoldPattern)(name)}.${schematic}.ts`,
             className: (0, string_utils_1.anyCaseToPascalCase)(name),
             moduleName: name,
@@ -219,29 +296,42 @@ const writeTemplate = ({ outputPath, template: { path, data }, }) => {
 };
 exports.writeTemplate = writeTemplate;
 /**
- * Returns the folder where the schematic should be placed
- * @param schematic
+ * Default folder mappings for opinionated scaffolding
+ */
+const DEFAULT_SCHEMATIC_FOLDERS = {
+    usecase: "useCases",
+    controller: "useCases",
+    dto: "useCases",
+    service: "useCases",
+    provider: "providers",
+    entity: "entities",
+    middleware: "middleware",
+    module: "useCases",
+    // NEW v4.0 schematics
+    interceptor: "interceptors",
+    event: "events",
+    handler: "events",
+    guard: "guards",
+    config: "config",
+};
+/**
+ * Returns the folder where the schematic should be placed.
+ * Uses scaffoldSchematics from config if defined, otherwise falls back to defaults.
+ *
+ * @param schematic - The schematic type (usecase, controller, etc.)
+ * @param scaffoldSchematics - Custom folder mappings from expressots.config.ts
+ * @returns The folder path for the schematic
  */
-const schematicFolder = (schematic) => {
-    switch (schematic) {
-        case "usecase":
-            return "useCases";
-        case "controller":
-            return "useCases";
-        case "dto":
-            return "useCases";
-        case "service":
-            return "useCases";
-        case "provider":
-            return "providers";
-        case "entity":
-            return "entities";
-        case "middleware":
-            return "providers/middlewares";
-        case "module":
-            return "useCases";
+const schematicFolder = (schematic, scaffoldSchematics) => {
+    // Check if custom mapping is defined in config
+    if (scaffoldSchematics) {
+        const customFolder = scaffoldSchematics[schematic];
+        if (customFolder) {
+            return customFolder;
+        }
     }
-    return undefined;
+    // Fall back to default mappings
+    return DEFAULT_SCHEMATIC_FOLDERS[schematic];
 };
 exports.schematicFolder = schematicFolder;
 /**
@@ -252,13 +342,13 @@ exports.schematicFolder = schematicFolder;
 const getNameWithScaffoldPattern = async (name) => {
     const configObject = await compiler_1.default.loadConfig();
     switch (configObject.scaffoldPattern) {
-        case "lowercase" /* Pattern.LOWER_CASE */:
+        case shared_1.Pattern.LOWER_CASE:
             return (0, string_utils_1.anyCaseToLowerCase)(name);
-        case "kebab-case" /* Pattern.KEBAB_CASE */:
+        case shared_1.Pattern.KEBAB_CASE:
             return (0, string_utils_1.anyCaseToKebabCase)(name);
-        case "PascalCase" /* Pattern.PASCAL_CASE */:
+        case shared_1.Pattern.PASCAL_CASE:
             return (0, string_utils_1.anyCaseToPascalCase)(name);
-        case "camelCase" /* Pattern.CAMEL_CASE */:
+        case shared_1.Pattern.CAMEL_CASE:
             return (0, string_utils_1.anyCaseToCamelCase)(name);
     }
 };
@@ -282,33 +372,40 @@ async function extractFirstWord(file) {
     const firstWord = f.split(regex)[0];
     const config = await compiler_1.default.loadConfig();
     switch (config.scaffoldPattern) {
-        case "lowercase" /* Pattern.LOWER_CASE */:
+        case shared_1.Pattern.LOWER_CASE:
             return (0, string_utils_1.anyCaseToLowerCase)(firstWord);
-        case "kebab-case" /* Pattern.KEBAB_CASE */:
+        case shared_1.Pattern.KEBAB_CASE:
             return (0, string_utils_1.anyCaseToKebabCase)(firstWord);
-        case "PascalCase" /* Pattern.PASCAL_CASE */:
+        case shared_1.Pattern.PASCAL_CASE:
             return (0, string_utils_1.anyCaseToPascalCase)(firstWord);
-        case "camelCase" /* Pattern.CAMEL_CASE */:
+        case shared_1.Pattern.CAMEL_CASE:
             return (0, string_utils_1.anyCaseToCamelCase)(firstWord);
     }
 }
 exports.extractFirstWord = extractFirstWord;
 /**
- * Check if the path is a nested path, a single path or a sugar path
+ * Determine the path style for a generate target.
+ *
+ * - `Nested`: contains an explicit separator (`billing/invoice`) → grouped
+ *   under the parent folder.
+ * - `Sugar`: a single segment that normalizes to more than one word
+ *   (`userCreate`, `user-create`, `user_create`, `UserCreate`) → grouped under
+ *   its first word as a shared module (e.g. `UserModule`). camelCase and
+ *   kebab-case forms of the same name therefore produce identical output.
+ * - `Single`: a true single-word target (`user`) → self-contained module in its
+ *   own folder.
+ *
  * @param path
  * @returns the path style
  */
 const checkPathStyle = (path) => {
-    const singleOrNestedPathRegex = /\/|\\/;
-    const sugarPathRegex = /^\w+-\w+$/;
-    if (singleOrNestedPathRegex.test(path)) {
+    const nestedPathRegex = /\/|\\/;
+    if (nestedPathRegex.test(path)) {
         return "nested" /* PathStyle.Nested */;
     }
-    else if (sugarPathRegex.test(path)) {
+    if ((0, string_utils_1.anyCaseToKebabCase)(path).includes("-")) {
         return "sugar" /* PathStyle.Sugar */;
     }
-    else {
-        return "single" /* PathStyle.Single */;
-    }
+    return "single" /* PathStyle.Single */;
 };
 exports.checkPathStyle = checkPathStyle;

package/bin/generate/utils/nonopininated-cmd.d.ts

@@ -1,9 +1,18 @@
 import { ExpressoConfig } from "@expressots/shared";
+/**
+ * Additional options for v4.0 schematics
+ */
+type V4Options = {
+    event?: string;
+    priority?: number;
+};
 /**
  * Process the non-opinionated command
  * @param schematic - The schematic
  * @param target - The target
  * @param method - The method
  * @param expressoConfig - The expresso config
+ * @param v4Options - Additional options for v4.0 schematics
  */
-export declare function nonOpinionatedProcess(schematic: string, target: string, method: string, expressoConfig: ExpressoConfig): Promise<string>;
+export declare function nonOpinionatedProcess(schematic: string, target: string, method: string, expressoConfig: ExpressoConfig, v4Options?: V4Options): Promise<string>;
+export {};