feat: enhance CLI and project commands with new utilities and path aliasing support

Author: rsaz

src/cli.ts

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 
 import chalk from "chalk";
-import { stdout } from "process";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import {
@@ -15,7 +14,7 @@ import { infoProject } from "./info";
 import { createProject } from "./new";
 import { addProviderCMD, removeProviderCMD } from "./providers";
 import { createExternalProviderCMD } from "./providers/create/cli";
-import { printError } from "./utils/cli-ui";
+import { printError, printHeader } from "./utils/cli-ui";
 import { scriptsCommand } from "./scripts";
 
 /**
@@ -24,7 +23,7 @@ import { scriptsCommand } from "./scripts";
  */
 export const BUNDLE_VERSION = "4.0.0-beta.1";
 
-stdout.write(`\n${[chalk.bold.green("🐎 Expressots")]}\n\n`);
+printHeader();
 
 yargs(hideBin(process.argv))
 	.scriptName("expressots")

src/commands/project.commands.ts

@@ -68,11 +68,13 @@ async function buildTsxArgs(opinionated: boolean): Promise<Array<string>> {
  *
  * @param opinionated - Whether to use opinionated configuration
  * @param verbose - Whether to show verbose nodemon output (for debugging)
+ * @param clear - Whether to clear console on restart (default: true)
  * @returns The nodemon arguments array
  */
 async function buildDevArgs(
 	opinionated: boolean,
 	verbose: boolean = false,
+	clear: boolean = true,
 ): Promise<Array<string>> {
 	const tsxArgs = await buildTsxArgs(opinionated);
 
@@ -83,6 +85,14 @@ async function buildDevArgs(
 		args.push("--quiet");
 	}
 
+	// Build the exec command with optional clear
+	const clearCmd = clear
+		? os.platform() === "win32"
+			? "cls &&"
+			: "clear &&"
+		: "";
+	const execCommand = `${clearCmd} tsx ${tsxArgs.join(" ")}`.trim();
+
 	// Core nodemon configuration
 	args.push(
 		"--signal",
@@ -98,7 +108,7 @@ async function buildDevArgs(
 		"--ignore",
 		"src/**/*.test.ts",
 		"--exec",
-		`tsx ${tsxArgs.join(" ")}`,
+		execCommand,
 	);
 
 	return args;
@@ -109,6 +119,7 @@ async function buildDevArgs(
  */
 interface DevCommandOptions {
 	verbose?: boolean;
+	clear?: boolean;
 }
 
 /**
@@ -126,9 +137,19 @@ export const devCommand: CommandModule<object, DevCommandOptions> = {
 			default: false,
 			description: "Show verbose nodemon output for debugging",
 		},
+		clear: {
+			alias: "c",
+			type: "boolean",
+			default: true,
+			description: "Clear console on restart (default: true)",
+		},
 	},
 	handler: async (argv) => {
-		await runCommand({ command: "dev", verbose: argv.verbose });
+		await runCommand({
+			command: "dev",
+			verbose: argv.verbose,
+			clear: argv.clear,
+		});
 	},
 };
 
@@ -352,6 +373,7 @@ const clearScreen = () => {
 interface RunCommandOptions {
 	command: string;
 	verbose?: boolean;
+	clear?: boolean;
 }
 
 /**
@@ -361,6 +383,7 @@ interface RunCommandOptions {
 export const runCommand = async ({
 	command,
 	verbose = false,
+	clear = true,
 }: RunCommandOptions): Promise<void> => {
 	const { opinionated, entryPoint } = await Compiler.loadConfig();
 	const outDir = getOutDir();
@@ -370,7 +393,7 @@ export const runCommand = async ({
 			case "dev":
 				await execCmd(
 					"nodemon",
-					await buildDevArgs(opinionated, verbose),
+					await buildDevArgs(opinionated, verbose, clear),
 				);
 				break;
 			case "build":

src/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 {}

src/generate/utils/command-utils.ts

@@ -11,6 +11,7 @@ import {
 import { printError } from "../../utils/cli-ui";
 import { verifyIfFileExists } from "../../utils/verify-file-exists";
 import Compiler from "../../utils/compiler";
+import { updateTsconfigPaths } from "../../utils/update-tsconfig-paths";
 import { ExpressoConfig, Pattern } from "@expressots/shared";
 
 export const enum PathStyle {
@@ -90,6 +91,11 @@ export async function validateAndPrepareFile(fp: FilePreparation) {
 		await verifyIfFileExists(outputPath, fp.schematic);
 		mkdirSync(`${folderToScaffold}/${path}`, { recursive: true });
 
+		// Update tsconfig paths dynamically (handles both default and custom folder names)
+		if (folderSchematic) {
+			await updateTsconfigPaths(folderSchematic, sourceRoot);
+		}
+
 		return {
 			path,
 			file,
@@ -219,34 +225,52 @@ export const splitTarget = async ({
 		if (schematic === "service") 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 = 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 getNameWithScaffoldPattern(
 					name,
 				)}.${schematic}.ts`,
 				className: anyCaseToPascalCase(name),
-				moduleName: wordName,
+				moduleName: firstWord,
 				modulePath: pathContent[0].split("-")[1],
 			};
 		}
 
 		// 3. Return the base case
 		return {
-			path: "",
+			path: shouldCreateFolder ? name : "",
 			file: `${await getNameWithScaffoldPattern(name)}.${schematic}.ts`,
 			className: anyCaseToPascalCase(name),
 			moduleName: name,

src/generate/utils/opinionated-cmd.ts

@@ -559,10 +559,13 @@ async function generateModuleServiceSugarPath(
 		},
 	});
 
+	// Extract folder name from folderToScaffold (e.g., "src/useCases" -> "useCases")
+	const folderName = nodePath.basename(folderToScaffold);
 	await addModuleToContainer(
 		anyCaseToPascalCase(moduleName),
 		`${moduleName}/${file.replace(".ts", "")}`,
 		path,
+		folderName,
 	);
 }
 
@@ -621,10 +624,13 @@ async function generateModuleServiceSinglePath(
 		},
 	});
 
+	// Extract folder name from folderToScaffold (e.g., "src/useCases" -> "useCases")
+	const folderName = nodePath.basename(folderToScaffold);
 	await addModuleToContainer(
 		anyCaseToPascalCase(moduleName),
 		`${moduleName}/${file.replace(".ts", "")}`,
 		path,
+		folderName,
 	);
 }
 
@@ -685,9 +691,12 @@ async function generateModuleServiceNestedPath(
 		},
 	});
 
+	// Extract folder name from folderToScaffold (e.g., "src/useCases" -> "useCases")
+	const folderName = nodePath.basename(folderToScaffold);
 	await addModuleToContainerNestedPath(
 		anyCaseToPascalCase(moduleFileName),
 		path,
+		folderName,
 	);
 }
 
@@ -773,7 +782,7 @@ async function generateHandler(
 			data: {
 				className: anyCaseToPascalCase(className),
 				eventName: anyCaseToPascalCase(eventName),
-				eventPath: `./${anyCaseToKebabCase(eventName)}.event`,
+				eventPath: `@events/${anyCaseToKebabCase(eventName)}.event`,
 				priority: priority.toString(),
 			},
 		},

src/new/form.ts

@@ -38,11 +38,27 @@ async function packageManagerInstall({
 		});
 
 		// Simulate incremental progress
-		let progress = 0;
+		// Start from 50% (where we left off) and go up to 88% max
+		// This leaves room for the actual completion and final steps
+		// On Windows, npm can be slow, so we continue updating to show activity
+		let progress = 50;
+		let lastProgressUpdate = Date.now();
 		const interval = setInterval(() => {
-			if (progress < 90) {
-				progress += 5;
-				progressBar.update(progress);
+			const now = Date.now();
+			// If we haven't received real progress updates in a while, continue incrementing
+			// This prevents the progress bar from appearing stuck on slow Windows systems
+			if (progress < 88) {
+				// Increment slower as we approach the limit to avoid hitting it too quickly
+				const increment = progress < 70 ? 3 : 1;
+				progress = Math.min(progress + increment, 88);
+				progressBar.update(progress, {
+					doing: "Installing dependencies...",
+				});
+			} else if (now - lastProgressUpdate > 3000) {
+				// Even at max, update the "doing" text to show it's still working
+				progressBar.update(progress, {
+					doing: "Installing dependencies...",
+				});
 			}
 		}, 1000);
 
@@ -56,15 +72,35 @@ async function packageManagerInstall({
 
 			if (npmProgressMatch) {
 				const [, current, total, task] = npmProgressMatch;
-				progress = Math.round(
-					(parseInt(current) / parseInt(total)) * 100,
-				);
+				// Map npm progress (0-100%) to our range (50-90%)
+				const npmProgress = (parseInt(current) / parseInt(total)) * 100;
+				progress = Math.round(50 + npmProgress * 0.4); // 50% + (0-100% * 0.4) = 50-90%
+				lastProgressUpdate = Date.now();
 				progressBar.update(progress, { doing: task });
-			} else {
+			} else if (cleanedOutput) {
+				lastProgressUpdate = Date.now();
 				progressBar.update(progress, { doing: cleanedOutput });
 			}
 		});
 
+		// On Windows, npm may output progress to stderr
+		installProcess.stderr?.on("data", (data: Buffer) => {
+			const output = data.toString().trim();
+			const cleanedOutput = output.replace(/\|\|.*$/g, "");
+			const npmProgressMatch = cleanedOutput.match(
+				/\[(\d+)\/(\d+)\] (?:npm )?([\w\s]+)\.{3}/,
+			);
+
+			if (npmProgressMatch) {
+				const [, current, total, task] = npmProgressMatch;
+				// Map npm progress (0-100%) to our range (50-90%)
+				const npmProgress = (parseInt(current) / parseInt(total)) * 100;
+				progress = Math.round(50 + npmProgress * 0.4); // 50% + (0-100% * 0.4) = 50-90%
+				lastProgressUpdate = Date.now();
+				progressBar.update(progress, { doing: task });
+			}
+		});
+
 		installProcess.on("error", (error) => {
 			clearInterval(interval);
 			progressBar.stop();
@@ -74,8 +110,8 @@ async function packageManagerInstall({
 		installProcess.on("close", (code) => {
 			clearInterval(interval);
 			if (code === 0) {
-				progressBar.update(100, { doing: "Complete!" });
-				progressBar.stop();
+				// Update to 90% to leave room for final steps (package name change)
+				progressBar.update(90, { doing: "Dependencies installed" });
 				resolve("Installation Done!");
 			} else {
 				progressBar.stop();
@@ -338,7 +374,11 @@ const projectForm = async (
 			});
 		}
 
-		progressBar.update(90);
+		// Progress should already be at 90% from packageManagerInstall
+		// Only update if we skipped installation
+		if (!SKIP_INSTALL_FOR_TESTING) {
+			progressBar.update(90, { doing: "Finalizing project" });
+		}
 
 		changePackageName({
 			directory: answer.name,