@expressots/cli 3.0.0-beta.4 → 4.0.0-preview.2

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

@@ -99,10 +99,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

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

@@ -34,6 +34,34 @@ 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");
+/**
+ * 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 +74,20 @@ 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,
         });
+        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 +110,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 });
@@ -158,28 +192,45 @@ 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();
+            // 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 +270,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;
 /**

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 {};

package/bin/generate/utils/nonopininated-cmd.js

@@ -10,8 +10,9 @@ const command_utils_1 = require("./command-utils");
  * @param target - The target
  * @param method - The method
  * @param expressoConfig - The expresso config
+ * @param v4Options - Additional options for v4.0 schematics
  */
-async function nonOpinionatedProcess(schematic, target, method, expressoConfig) {
+async function nonOpinionatedProcess(schematic, target, method, expressoConfig, v4Options = {}) {
     let f = await (0, command_utils_1.validateAndPrepareFile)({
         schematic,
         target,
@@ -81,6 +82,27 @@ async function nonOpinionatedProcess(schematic, target, method, expressoConfig)
             await generateModule(f.outputPath, f.className, f.moduleName, f.path, f.schematic);
             await (0, cli_ui_1.printGenerateSuccess)(f.schematic, f.file);
             break;
+        // NEW v4.0 schematics
+        case "interceptor":
+            await generateInterceptor(f.outputPath, f.className, v4Options.priority ?? 10);
+            await (0, cli_ui_1.printGenerateSuccess)("interceptor", f.file);
+            break;
+        case "event":
+            await generateEvent(f.outputPath, f.className);
+            await (0, cli_ui_1.printGenerateSuccess)("event", f.file);
+            break;
+        case "handler":
+            await generateHandler(f.outputPath, f.className, v4Options.event ?? "MyEvent", v4Options.priority ?? 10);
+            await (0, cli_ui_1.printGenerateSuccess)("handler", f.file);
+            break;
+        case "guard":
+            await generateGuard(f.outputPath, f.className);
+            await (0, cli_ui_1.printGenerateSuccess)("guard", f.file);
+            break;
+        case "config":
+            await generateConfig(f.outputPath, f.className, f.moduleName);
+            await (0, cli_ui_1.printGenerateSuccess)("config", f.file);
+            break;
     }
     return f.file;
 }
@@ -248,3 +270,80 @@ async function generateModule(outputPath, className, moduleName, path, schematic
         },
     });
 }
+// NEW v4.0 Schematic Generators
+/**
+ * Generate an interceptor
+ */
+async function generateInterceptor(outputPath, className, priority) {
+    (0, command_utils_1.writeTemplate)({
+        outputPath,
+        template: {
+            path: "../templates/nonopinionated/interceptor.tpl",
+            data: {
+                className: (0, string_utils_1.anyCaseToPascalCase)(className),
+                priority: priority.toString(),
+            },
+        },
+    });
+}
+/**
+ * Generate an event
+ */
+async function generateEvent(outputPath, className) {
+    (0, command_utils_1.writeTemplate)({
+        outputPath,
+        template: {
+            path: "../templates/nonopinionated/event.tpl",
+            data: {
+                className: (0, string_utils_1.anyCaseToPascalCase)(className),
+            },
+        },
+    });
+}
+/**
+ * Generate an event handler
+ */
+async function generateHandler(outputPath, className, eventName, priority) {
+    (0, command_utils_1.writeTemplate)({
+        outputPath,
+        template: {
+            path: "../templates/nonopinionated/handler.tpl",
+            data: {
+                className: (0, string_utils_1.anyCaseToPascalCase)(className),
+                eventName: (0, string_utils_1.anyCaseToPascalCase)(eventName),
+                eventPath: `./${(0, string_utils_1.anyCaseToKebabCase)(eventName)}.event`,
+                priority: priority.toString(),
+            },
+        },
+    });
+}
+/**
+ * Generate a guard
+ */
+async function generateGuard(outputPath, className) {
+    (0, command_utils_1.writeTemplate)({
+        outputPath,
+        template: {
+            path: "../templates/nonopinionated/guard.tpl",
+            data: {
+                className: (0, string_utils_1.anyCaseToPascalCase)(className),
+            },
+        },
+    });
+}
+/**
+ * Generate a config module
+ */
+async function generateConfig(outputPath, className, moduleName) {
+    (0, command_utils_1.writeTemplate)({
+        outputPath,
+        template: {
+            path: "../templates/nonopinionated/config.tpl",
+            data: {
+                className: (0, string_utils_1.anyCaseToPascalCase)(className),
+                moduleName: (0, string_utils_1.anyCaseToCamelCase)(moduleName || className),
+                envPrefix: (0, string_utils_1.anyCaseToUpperSnakeCase)(className),
+            },
+        },
+    });
+}

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

@@ -1,4 +1,11 @@
 import { ExpressoConfig } from "@expressots/shared";
+/**
+ * Additional options for v4.0 schematics
+ */
+type V4Options = {
+    event?: string;
+    priority?: number;
+};
 /**
  * Process commands for opinionated service scaffolding
  * @param schematic - Resource to scaffold
@@ -6,6 +13,8 @@ import { ExpressoConfig } from "@expressots/shared";
  * @param method - HTTP method
  * @param expressoConfig - Expresso configuration [expressots.config.ts]
  * @param pathStyle - Path command style [sugar, nested, single]
+ * @param v4Options - Additional options for v4.0 schematics
  * @returns
  */
-export declare function opinionatedProcess(schematic: string, target: string, method: string, expressoConfig: ExpressoConfig, pathStyle: string): Promise<string>;
+export declare function opinionatedProcess(schematic: string, target: string, method: string, expressoConfig: ExpressoConfig, pathStyle: string, v4Options?: V4Options): Promise<string>;
+export {};