@expressots/cli 3.0.0 → 4.0.0-preview.3

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

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

@@ -41,9 +41,10 @@ const add_module_to_container_1 = require("../../utils/add-module-to-container")
  * @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
  */
-async function opinionatedProcess(schematic, target, method, expressoConfig, pathStyle) {
+async function opinionatedProcess(schematic, target, method, expressoConfig, pathStyle, v4Options = {}) {
     const f = await (0, command_utils_1.validateAndPrepareFile)({
         schematic,
         target,
@@ -73,19 +74,20 @@ async function opinionatedProcess(schematic, target, method, expressoConfig, pat
                 method,
                 expressoConfig,
             });
+            let moduleFile = m.file;
             if (pathStyle === "sugar" /* PathStyle.Sugar */) {
-                await generateModuleServiceSugarPath(f.outputPath, m.className, m.moduleName, m.path, m.file, m.folderToScaffold);
+                moduleFile = await generateModuleServiceSugarPath(f.outputPath, m.className, m.moduleName, m.path, m.folderToScaffold);
             }
             else if (pathStyle === "nested" /* PathStyle.Nested */) {
-                await generateModuleServiceNestedPath(f.outputPath, m.className, m.path, m.folderToScaffold);
+                moduleFile = await generateModuleServiceNestedPath(f.outputPath, m.className, m.path, m.folderToScaffold);
             }
             else if (pathStyle === "single" /* PathStyle.Single */) {
-                await generateModuleServiceSinglePath(f.outputPath, m.className, m.moduleName, m.path, m.file, m.folderToScaffold);
+                moduleFile = await generateModuleServiceSinglePath(f.outputPath, m.className, m.moduleName, m.path, m.file, m.folderToScaffold);
             }
             await (0, cli_ui_1.printGenerateSuccess)("controller", f.file);
             await (0, cli_ui_1.printGenerateSuccess)("usecase", f.file);
             await (0, cli_ui_1.printGenerateSuccess)("dto", f.file);
-            await (0, cli_ui_1.printGenerateSuccess)("module", f.file);
+            await (0, cli_ui_1.printGenerateSuccess)("module", moduleFile);
             break;
         }
         case "usecase":
@@ -116,6 +118,27 @@ async function opinionatedProcess(schematic, target, method, expressoConfig, pat
             await generateModule(f.outputPath, f.className, f.moduleName, f.path);
             await (0, cli_ui_1.printGenerateSuccess)(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;
 }
@@ -347,13 +370,16 @@ async function generateMiddleware(outputPath, className, moduleName, path) {
  * @param moduleName - The module name
  * @param path - The path
  */
-async function generateModuleServiceSugarPath(outputPathController, className, moduleName, path, file, folderToScaffold) {
-    const newModuleFile = await (0, command_utils_1.extractFirstWord)(file);
+async function generateModuleServiceSugarPath(outputPathController, className, moduleName, path, folderToScaffold) {
+    // The module file is named after the feature (first word), e.g. `user`, and
+    // lives at the feature root (`useCases/user/user.module.ts`), grouping all of
+    // the feature's use-cases. `moduleName` already carries the feature word.
+    const newModuleFile = await (0, command_utils_1.getNameWithScaffoldPattern)(moduleName);
     const newModulePath = nodePath
         .join(folderToScaffold, path, "..")
         .normalize();
     const newModuleName = `${newModuleFile}.module.ts`;
-    const newModuleOutputPath = `${newModulePath}/${newModuleName}`.replace("\\", "/");
+    const newModuleOutputPath = `${newModulePath}/${newModuleName}`.replace(/\\/g, "/");
     const controllerToModule = nodePath
         .relative(newModuleOutputPath, outputPathController)
         .normalize()
@@ -365,7 +391,7 @@ async function generateModuleServiceSugarPath(outputPathController, className, m
         .normalize();
     if (fs_1.default.existsSync(newModuleOutputPath)) {
         await (0, add_controller_to_module_1.addControllerToModule)(controllerFullPath, `${className}Controller`, controllerToModule);
-        return;
+        return newModuleName;
     }
     (0, command_utils_1.writeTemplate)({
         outputPath: newModuleOutputPath,
@@ -378,7 +404,10 @@ async function generateModuleServiceSugarPath(outputPathController, className, m
             },
         },
     });
-    await (0, add_module_to_container_1.addModuleToContainer)((0, string_utils_1.anyCaseToPascalCase)(moduleName), `${moduleName}/${file.replace(".ts", "")}`, path);
+    // Extract folder name from folderToScaffold (e.g., "src/useCases" -> "useCases")
+    const folderName = nodePath.basename(folderToScaffold);
+    await (0, add_module_to_container_1.addModuleToContainerByPath)(`${(0, string_utils_1.anyCaseToPascalCase)(moduleName)}Module`, newModuleOutputPath, folderToScaffold, folderName);
+    return newModuleName;
 }
 /**
  * Generate a module for service scaffolding with single path
@@ -391,7 +420,7 @@ async function generateModuleServiceSinglePath(outputPathController, className,
     const newModuleFile = await (0, command_utils_1.extractFirstWord)(file);
     const newModulePath = nodePath.join(folderToScaffold, path).normalize();
     const newModuleName = `${newModuleFile}.module.ts`;
-    const newModuleOutputPath = `${newModulePath}/${newModuleName}`.replace("\\", "/");
+    const newModuleOutputPath = `${newModulePath}/${newModuleName}`.replace(/\\/g, "/");
     const controllerToModule = nodePath
         .relative(newModuleOutputPath, outputPathController)
         .normalize()
@@ -403,7 +432,7 @@ async function generateModuleServiceSinglePath(outputPathController, className,
         .normalize();
     if (fs_1.default.existsSync(newModuleOutputPath)) {
         await (0, add_controller_to_module_1.addControllerToModule)(controllerFullPath, `${className}Controller`, controllerToModule);
-        return;
+        return newModuleName;
     }
     (0, command_utils_1.writeTemplate)({
         outputPath: newModuleOutputPath,
@@ -416,7 +445,10 @@ async function generateModuleServiceSinglePath(outputPathController, className,
             },
         },
     });
-    await (0, add_module_to_container_1.addModuleToContainer)((0, string_utils_1.anyCaseToPascalCase)(moduleName), `${moduleName}/${file.replace(".ts", "")}`, path);
+    // Extract folder name from folderToScaffold (e.g., "src/useCases" -> "useCases")
+    const folderName = nodePath.basename(folderToScaffold);
+    await (0, add_module_to_container_1.addModuleToContainerByPath)(`${(0, string_utils_1.anyCaseToPascalCase)(moduleName)}Module`, newModuleOutputPath, folderToScaffold, folderName);
+    return newModuleName;
 }
 /**
  * Generate a module for service scaffolding with nested path
@@ -432,7 +464,7 @@ async function generateModuleServiceNestedPath(outputPathController, className,
         .join(folderToScaffold, path, "..")
         .normalize();
     const newModuleName = `${moduleFileName}.module.ts`;
-    const newModuleOutputPath = `${newModulePath}/${newModuleName}`.replace("\\", "/");
+    const newModuleOutputPath = `${newModulePath}/${newModuleName}`.replace(/\\/g, "/");
     const controllerToModule = nodePath
         .relative(newModuleOutputPath, outputPathController)
         .normalize()
@@ -444,7 +476,7 @@ async function generateModuleServiceNestedPath(outputPathController, className,
         .normalize();
     if (fs_1.default.existsSync(newModuleOutputPath)) {
         await (0, add_controller_to_module_1.addControllerToModule)(controllerFullPath, `${className}Controller`, controllerToModule);
-        return;
+        return newModuleName;
     }
     (0, command_utils_1.writeTemplate)({
         outputPath: newModuleOutputPath,
@@ -457,7 +489,10 @@ async function generateModuleServiceNestedPath(outputPathController, className,
             },
         },
     });
-    await (0, add_module_to_container_1.addModuleToContainerNestedPath)((0, string_utils_1.anyCaseToPascalCase)(moduleFileName), path);
+    // Extract folder name from folderToScaffold (e.g., "src/useCases" -> "useCases")
+    const folderName = nodePath.basename(folderToScaffold);
+    await (0, add_module_to_container_1.addModuleToContainerByPath)(`${(0, string_utils_1.anyCaseToPascalCase)(moduleFileName)}Module`, newModuleOutputPath, folderToScaffold, folderName);
+    return newModuleName;
 }
 /**
  * Generate a module
@@ -479,3 +514,80 @@ async function generateModule(outputPath, className, moduleName, path) {
         },
     });
 }
+// NEW v4.0 Schematic Generators
+/**
+ * Generate an interceptor
+ */
+async function generateInterceptor(outputPath, className, priority) {
+    (0, command_utils_1.writeTemplate)({
+        outputPath,
+        template: {
+            path: "../templates/opinionated/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/opinionated/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/opinionated/handler.tpl",
+            data: {
+                className: (0, string_utils_1.anyCaseToPascalCase)(className),
+                eventName: (0, string_utils_1.anyCaseToPascalCase)(eventName),
+                eventPath: `@events/${(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/opinionated/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/opinionated/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/string-utils.d.ts

@@ -34,3 +34,9 @@ export declare function anyCaseToUpperCase(str: string): string;
  * @returns The converted string in lower case.
  */
 export declare function anyCaseToLowerCase(str: string): string;
+/**
+ * Converts a string from any case (camelCase, PascalCase, kebab-case, snake_case) to UPPER_SNAKE_CASE.
+ * @param str - The input string to be converted.
+ * @returns The converted string in UPPER_SNAKE_CASE.
+ */
+export declare function anyCaseToUpperSnakeCase(str: string): string;

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.anyCaseToLowerCase = exports.anyCaseToUpperCase = exports.anyCaseToSnakeCase = exports.anyCaseToPascalCase = exports.anyCaseToKebabCase = exports.anyCaseToCamelCase = void 0;
+exports.anyCaseToUpperSnakeCase = exports.anyCaseToLowerCase = exports.anyCaseToUpperCase = exports.anyCaseToSnakeCase = exports.anyCaseToPascalCase = exports.anyCaseToKebabCase = exports.anyCaseToCamelCase = void 0;
 /**
  * Converts a string from any case (camelCase, PascalCase, kebab-case, snake_case) to camelCase.
  * @param str - The input string to be converted.
@@ -69,3 +69,15 @@ function anyCaseToLowerCase(str) {
         .toLowerCase();
 }
 exports.anyCaseToLowerCase = anyCaseToLowerCase;
+/**
+ * Converts a string from any case (camelCase, PascalCase, kebab-case, snake_case) to UPPER_SNAKE_CASE.
+ * @param str - The input string to be converted.
+ * @returns The converted string in UPPER_SNAKE_CASE.
+ */
+function anyCaseToUpperSnakeCase(str) {
+    return str
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/[-]+/g, "_")
+        .toUpperCase();
+}
+exports.anyCaseToUpperSnakeCase = anyCaseToUpperSnakeCase;

package/bin/help/cli.d.ts

@@ -1,4 +1,4 @@
 import { CommandModule } from "yargs";
-type CommandModuleArgs = {};
+type CommandModuleArgs = Record<string, never>;
 declare const helpCommand: () => CommandModule<CommandModuleArgs, any>;
 export { helpCommand };

package/bin/help/command-help-registry.d.ts

@@ -0,0 +1,23 @@
+import { type CommandHelpSpec } from "./command-help";
+/**
+ * Structured help specs for the subcommands whose option-heavy `--help` would
+ * otherwise render as yargs' sprawling default table. Keeping them here lets
+ * the central interceptor in `cli.ts` render a refined, grouped screen that
+ * matches the rest of the CLI without touching each command's yargs builder.
+ *
+ * NOTE: these mirror the option definitions in each command's `cli.ts`. When
+ * an option/choice/default changes there, update the matching entry here.
+ */
+declare const SPECS: CommandHelpSpec[];
+/**
+ * Resolve a command token (name or alias) to its help spec, if any.
+ */
+export declare function resolveCommandHelpSpec(token: string): CommandHelpSpec | undefined;
+/**
+ * Detect a `<command> --help` / `<command> -h` invocation and, if the command
+ * has a registered spec, render the refined help screen.
+ *
+ * @returns `true` when custom help was printed (caller should exit), else `false`.
+ */
+export declare function tryPrintCommandHelp(args: string[], version?: string): boolean;
+export { SPECS as COMMAND_HELP_SPECS };