@expressots/cli 4.0.0-preview.2 → 4.0.0-preview.3

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

@@ -74,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":
@@ -369,8 +370,11 @@ 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();
@@ -387,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,
@@ -402,7 +406,8 @@ async function generateModuleServiceSugarPath(outputPathController, className, m
     });
     // Extract folder name from folderToScaffold (e.g., "src/useCases" -> "useCases")
     const folderName = nodePath.basename(folderToScaffold);
-    await (0, add_module_to_container_1.addModuleToContainer)((0, string_utils_1.anyCaseToPascalCase)(moduleName), `${moduleName}/${file.replace(".ts", "")}`, path, folderName);
+    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
@@ -427,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,
@@ -442,7 +447,8 @@ async function generateModuleServiceSinglePath(outputPathController, className,
     });
     // Extract folder name from folderToScaffold (e.g., "src/useCases" -> "useCases")
     const folderName = nodePath.basename(folderToScaffold);
-    await (0, add_module_to_container_1.addModuleToContainer)((0, string_utils_1.anyCaseToPascalCase)(moduleName), `${moduleName}/${file.replace(".ts", "")}`, path, folderName);
+    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
@@ -470,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,
@@ -485,7 +491,8 @@ async function generateModuleServiceNestedPath(outputPathController, className,
     });
     // Extract folder name from folderToScaffold (e.g., "src/useCases" -> "useCases")
     const folderName = nodePath.basename(folderToScaffold);
-    await (0, add_module_to_container_1.addModuleToContainerNestedPath)((0, string_utils_1.anyCaseToPascalCase)(moduleFileName), path, folderName);
+    await (0, add_module_to_container_1.addModuleToContainerByPath)(`${(0, string_utils_1.anyCaseToPascalCase)(moduleFileName)}Module`, newModuleOutputPath, folderToScaffold, folderName);
+    return newModuleName;
 }
 /**
  * Generate a module

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

package/bin/help/command-help-registry.js

@@ -0,0 +1,303 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMAND_HELP_SPECS = exports.tryPrintCommandHelp = exports.resolveCommandHelpSpec = void 0;
+const command_help_1 = require("./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.
+ */
+const SPECS = [
+    {
+        name: "costs",
+        aliases: ["cost", "pricing"],
+        usage: "expressots costs <action> [options]",
+        description: "Estimate and compare cloud deployment costs.",
+        groups: [
+            {
+                title: "Actions",
+                entries: [
+                    (0, command_help_1.helpEntry)("estimate", "Estimate cost for a provider/service"),
+                    (0, command_help_1.helpEntry)("compare", "Compare costs across providers"),
+                    (0, command_help_1.helpEntry)("optimize", "Suggest cost optimizations"),
+                    (0, command_help_1.helpEntry)("pricing", "Show current pricing data"),
+                    (0, command_help_1.helpEntry)("update", "Refresh pricing data from remote"),
+                    (0, command_help_1.helpEntry)("info", "Show pricing system status & providers"),
+                ],
+            },
+            {
+                title: "Options",
+                entries: [
+                    (0, command_help_1.helpEntry)("-p, --provider", "Cloud provider", "aws, gcp, azure, railway, render, fly, digitalocean, heroku"),
+                    (0, command_help_1.helpEntry)("-s, --service", "Service type", "ecs, eks, lambda, cloudrun, gke, aci, aks, web-service"),
+                    (0, command_help_1.helpEntry)("-i, --instances", "Instances / replicas", "default: 1"),
+                    (0, command_help_1.helpEntry)("-c, --cpu", "vCPUs per instance", "default: 1"),
+                    (0, command_help_1.helpEntry)("-m, --memory", "Memory (GB) per instance", "default: 1"),
+                    (0, command_help_1.helpEntry)("--storage", "Storage in GB", "default: 10"),
+                    (0, command_help_1.helpEntry)("--bandwidth", "Bandwidth GB/month", "default: 100"),
+                    (0, command_help_1.helpEntry)("-r, --region", "Cloud region", "default: us-east-1"),
+                    (0, command_help_1.helpEntry)("--hours", "Running hours/month", "default: 720"),
+                    (0, command_help_1.helpEntry)("--format", "Output format", "text, json, markdown · default: text"),
+                    (0, command_help_1.helpEntry)("-o, --output", "Write output to a file"),
+                ],
+            },
+        ],
+    },
+    {
+        name: "cicd",
+        aliases: ["ci", "pipeline"],
+        usage: "expressots cicd <action> [platform] [options]",
+        description: "Generate and manage CI/CD pipeline configurations.",
+        groups: [
+            {
+                title: "Actions",
+                entries: [
+                    (0, command_help_1.helpEntry)("init", "Interactive pipeline setup"),
+                    (0, command_help_1.helpEntry)("generate", "Generate pipeline configuration"),
+                    (0, command_help_1.helpEntry)("list", "List supported platforms"),
+                    (0, command_help_1.helpEntry)("validate", "Validate existing pipelines"),
+                ],
+            },
+            {
+                title: "Arguments",
+                entries: [
+                    (0, command_help_1.helpEntry)("platform", "CI/CD platform", "github, gitlab, circleci, jenkins, bitbucket, azure, all"),
+                ],
+            },
+            {
+                title: "Options",
+                entries: [
+                    (0, command_help_1.helpEntry)("-s, --strategy", "Pipeline strategy", "basic, comprehensive, security-focused · default: comprehensive"),
+                    (0, command_help_1.helpEntry)("--include-security", "Security scanning (Trivy, Snyk)", "default: true"),
+                    (0, command_help_1.helpEntry)("--include-e2e", "End-to-end tests", "default: false"),
+                    (0, command_help_1.helpEntry)("--include-coverage", "Coverage reporting", "default: true"),
+                    (0, command_help_1.helpEntry)("-r, --docker-registry", "Docker registry URL", "e.g. ghcr.io, docker.io"),
+                    (0, command_help_1.helpEntry)("--deploy-target", "Deploy target", "kubernetes, ecs, cloudrun, railway, render, fly, none · default: none"),
+                    (0, command_help_1.helpEntry)("-b, --branch", "Trigger branch", "default: main"),
+                    (0, command_help_1.helpEntry)("--node-version", "Node.js version", "default: 20"),
+                    (0, command_help_1.helpEntry)("-o, --output-dir", "Output directory"),
+                ],
+            },
+        ],
+    },
+    {
+        name: "migrate",
+        aliases: ["migration", "mig"],
+        usage: "expressots migrate <action> [options]",
+        description: "Generate migration scripts between cloud platforms.",
+        groups: [
+            {
+                title: "Actions",
+                entries: [
+                    (0, command_help_1.helpEntry)("init", "Interactive migration setup"),
+                    (0, command_help_1.helpEntry)("generate", "Generate migration scripts"),
+                    (0, command_help_1.helpEntry)("list", "List supported platforms"),
+                    (0, command_help_1.helpEntry)("analyze", "Analyze a migration path"),
+                ],
+            },
+            {
+                title: "Options",
+                entries: [
+                    (0, command_help_1.helpEntry)("-f, --from", "Source platform", "heroku, docker-compose, vercel, aws-ecs, gcp-cloudrun, azure-container"),
+                    (0, command_help_1.helpEntry)("-t, --to", "Target platform", "railway, render, fly, kubernetes, aws-ecs, gcp-cloudrun, azure-container"),
+                    (0, command_help_1.helpEntry)("--include-data", "Include data migration", "default: false"),
+                    (0, command_help_1.helpEntry)("--include-secrets", "Include secrets/env migration", "default: true"),
+                    (0, command_help_1.helpEntry)("--dry-run", "Preview without writing files", "default: false"),
+                    (0, command_help_1.helpEntry)("-o, --output-dir", "Output directory", "default: ./migration"),
+                ],
+            },
+        ],
+    },
+    {
+        name: "profile",
+        aliases: ["prof", "analyze"],
+        usage: "expressots profile <action> [target] [options]",
+        description: "Analyze and optimize container configurations.",
+        groups: [
+            {
+                title: "Actions",
+                entries: [
+                    (0, command_help_1.helpEntry)("container", "Analyze a container configuration"),
+                    (0, command_help_1.helpEntry)("image", "Analyze a Docker image"),
+                    (0, command_help_1.helpEntry)("optimize", "Suggest Dockerfile optimizations"),
+                    (0, command_help_1.helpEntry)("report", "Show the latest profile report"),
+                ],
+            },
+            {
+                title: "Arguments",
+                entries: [(0, command_help_1.helpEntry)("target", "Dockerfile path or image name")],
+            },
+            {
+                title: "Options",
+                entries: [
+                    (0, command_help_1.helpEntry)("-f, --dockerfile", "Path to Dockerfile", "default: Dockerfile"),
+                    (0, command_help_1.helpEntry)("--format", "Output format", "text, json, html · default: text"),
+                    (0, command_help_1.helpEntry)("--severity", "Minimum severity", "low, medium, high, critical · default: low"),
+                    (0, command_help_1.helpEntry)("--auto-fix", "Apply safe optimizations", "default: false"),
+                    (0, command_help_1.helpEntry)("-o, --output", "Output file for report"),
+                    (0, command_help_1.helpEntry)("--include-security", "Security vulnerability scan", "default: true"),
+                    (0, command_help_1.helpEntry)("--include-size", "Size analysis", "default: true"),
+                ],
+            },
+        ],
+    },
+    {
+        name: "containerize",
+        aliases: ["ctr"],
+        usage: "expressots containerize [target] [environment] [options]",
+        description: "Generate container configurations for your ExpressoTS application.",
+        groups: [
+            {
+                title: "Arguments",
+                entries: [
+                    (0, command_help_1.helpEntry)("target", "Target platform", "docker, kubernetes, k8s, compose · default: docker"),
+                    (0, command_help_1.helpEntry)("environment", "Target environment", "development, staging, production, all · default: production"),
+                ],
+            },
+            {
+                title: "Options",
+                entries: [
+                    (0, command_help_1.helpEntry)("--preset", "Container preset", "minimal, secure, fast-startup, dev, multi-arch, standard · default: standard"),
+                    (0, command_help_1.helpEntry)("--analyze", "Analyze project before generating", "default: true"),
+                    (0, command_help_1.helpEntry)("--skip-compose", "Skip docker-compose.yml", "default: false"),
+                    (0, command_help_1.helpEntry)("--include-ci", "Include CI/CD pipeline", "default: false"),
+                    (0, command_help_1.helpEntry)("--ci-platform", "CI/CD platform", "github, gitlab, circleci, jenkins, bitbucket, azure, all · default: github"),
+                    (0, command_help_1.helpEntry)("--ci-strategy", "CI/CD strategy", "basic, comprehensive, security-focused · default: comprehensive"),
+                    (0, command_help_1.helpEntry)("--include-security-scans", "Security scanning (Trivy, Snyk)", "default: true"),
+                    (0, command_help_1.helpEntry)("--include-e2e", "End-to-end tests in CI", "default: false"),
+                ],
+            },
+        ],
+    },
+    {
+        name: "container-dev",
+        aliases: ["cdev", "docker-dev"],
+        usage: "expressots container-dev [action] [options]",
+        description: "Develop inside Docker containers with hot reload.",
+        groups: [
+            {
+                title: "Actions",
+                entries: [
+                    (0, command_help_1.helpEntry)("start", "Start the dev container (default)"),
+                    (0, command_help_1.helpEntry)("stop", "Stop the dev container"),
+                    (0, command_help_1.helpEntry)("attach", "Attach to the running container"),
+                    (0, command_help_1.helpEntry)("shell", "Open a shell in the container"),
+                    (0, command_help_1.helpEntry)("status", "Show container status"),
+                    (0, command_help_1.helpEntry)("logs", "Show container logs"),
+                ],
+            },
+            {
+                title: "Options",
+                entries: [
+                    (0, command_help_1.helpEntry)("-c, --container", "Run dev inside Docker", "default: false"),
+                    (0, command_help_1.helpEntry)("-s, --service", "Compose service name", "default: app"),
+                    (0, command_help_1.helpEntry)("-f, --compose-file", "docker-compose file", "default: docker-compose.development.yml"),
+                    (0, command_help_1.helpEntry)("-b, --build", "Rebuild before starting", "default: false"),
+                    (0, command_help_1.helpEntry)("-d, --detach", "Run in background", "default: false"),
+                    (0, command_help_1.helpEntry)("-p, --port", "Override application port"),
+                    (0, command_help_1.helpEntry)("--debug-port", "Node inspector port", "default: 9229"),
+                    (0, command_help_1.helpEntry)("-w, --watch", "File watching / hot reload", "default: true"),
+                    (0, command_help_1.helpEntry)("--follow", "Follow logs (logs action)", "default: true"),
+                    (0, command_help_1.helpEntry)("--tail", "Log lines to show", "default: 100"),
+                ],
+            },
+        ],
+    },
+    {
+        name: "templates",
+        aliases: ["tpl"],
+        usage: "expressots templates <action> [args...] [options]",
+        description: "Manage CLI templates for CI/CD, Docker, and Kubernetes.",
+        groups: [
+            {
+                title: "Actions",
+                entries: [
+                    (0, command_help_1.helpEntry)("list", "List available templates"),
+                    (0, command_help_1.helpEntry)("update", "Update template cache from remote"),
+                    (0, command_help_1.helpEntry)("clear", "Clear local template cache"),
+                    (0, command_help_1.helpEntry)("info", "Show template info (info <category> <platform>)"),
+                    (0, command_help_1.helpEntry)("repo", "View / set / reset template repository"),
+                    (0, command_help_1.helpEntry)("status", "Show template system status"),
+                ],
+            },
+            {
+                title: "Options",
+                entries: [
+                    (0, command_help_1.helpEntry)("-c, --category", "Filter by category", "cicd, docker, kubernetes, migrations"),
+                    (0, command_help_1.helpEntry)("-p, --platform", "Filter by platform", "github, gitlab, ..."),
+                ],
+            },
+        ],
+        notes: [
+            "Examples:",
+            "  expressots templates list",
+            "  expressots templates info cicd github",
+            "  expressots templates repo set https://github.com/org/templates",
+        ],
+    },
+    {
+        name: "dev",
+        usage: "expressots dev [options]",
+        description: "Start the development server.",
+        groups: [
+            {
+                title: "Options",
+                entries: [
+                    (0, command_help_1.helpEntry)("-c, --container", "Run dev inside Docker", "default: false"),
+                    (0, command_help_1.helpEntry)("-b, --build", "Rebuild container before starting", "with --container"),
+                    (0, command_help_1.helpEntry)("-d, --detach", "Run container in background", "with --container"),
+                ],
+            },
+        ],
+    },
+];
+exports.COMMAND_HELP_SPECS = SPECS;
+/**
+ * Index every spec by its canonical name and aliases for O(1) lookup.
+ */
+const SPEC_INDEX = (() => {
+    const index = new Map();
+    for (const spec of SPECS) {
+        index.set(spec.name, spec);
+        for (const alias of spec.aliases ?? []) {
+            index.set(alias, spec);
+        }
+    }
+    return index;
+})();
+/**
+ * Resolve a command token (name or alias) to its help spec, if any.
+ */
+function resolveCommandHelpSpec(token) {
+    return SPEC_INDEX.get(token);
+}
+exports.resolveCommandHelpSpec = resolveCommandHelpSpec;
+/**
+ * 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`.
+ */
+function tryPrintCommandHelp(args, version) {
+    const command = args[0];
+    if (!command || command.startsWith("-")) {
+        return false;
+    }
+    const wantsHelp = args
+        .slice(1)
+        .some((arg) => arg === "--help" || arg === "-h");
+    if (!wantsHelp) {
+        return false;
+    }
+    const spec = resolveCommandHelpSpec(command);
+    if (!spec) {
+        return false;
+    }
+    (0, command_help_1.printCommandHelp)(spec, version);
+    return true;
+}
+exports.tryPrintCommandHelp = tryPrintCommandHelp;

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

@@ -0,0 +1,36 @@
+import { type HelpEntry, type HelpGroup } from "./render";
+/**
+ * A structured description of a single command's help surface. Rendered by
+ * {@link printCommandHelp} so every subcommand `--help` shares the exact visual
+ * language of the top-level help screen (see `main-help.ts`) and the command
+ * reference (`help/form.ts`), instead of yargs' sprawling default table.
+ */
+export interface CommandHelpSpec {
+    /** Canonical command name, e.g. `costs`. */
+    name: string;
+    /** Command aliases, e.g. `["cost", "pricing"]`. */
+    aliases?: string[];
+    /** Usage line, e.g. `expressots costs <action> [options]`. */
+    usage: string;
+    /** One-line description (matches the yargs `describe`). */
+    description: string;
+    /** Titled groups of entries (Arguments, Actions, Options, ...). */
+    groups: HelpGroup[];
+    /** Optional trailing notes / examples (rendered dim). */
+    notes?: string[];
+    /** Optional docs URL. */
+    docs?: string;
+}
+/**
+ * Build an option/argument entry with an optional dim "hint" (choices,
+ * defaults, examples) appended to the description. Keeps the help compact while
+ * still surfacing the metadata yargs would otherwise sprawl across the line.
+ */
+export declare function helpEntry(name: string, desc: string, hint?: string): HelpEntry;
+/**
+ * Print a refined, grouped, column-aligned help screen for a single command.
+ *
+ * Each group is rendered with its own column width so short action names and
+ * long option flags both stay tightly aligned.
+ */
+export declare function printCommandHelp(spec: CommandHelpSpec, version?: string): void;

package/bin/help/command-help.js

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printCommandHelp = exports.helpEntry = void 0;
+const chalk_1 = __importDefault(require("chalk"));
+const process_1 = require("process");
+const render_1 = require("./render");
+const DEFAULT_DOCS = "https://doc.expresso-ts.com/docs/category/cli";
+/**
+ * Build an option/argument entry with an optional dim "hint" (choices,
+ * defaults, examples) appended to the description. Keeps the help compact while
+ * still surfacing the metadata yargs would otherwise sprawl across the line.
+ */
+function helpEntry(name, desc, hint) {
+    return { name, desc: hint ? `${desc} ${chalk_1.default.dim(`(${hint})`)}` : desc };
+}
+exports.helpEntry = helpEntry;
+/**
+ * Print a refined, grouped, column-aligned help screen for a single command.
+ *
+ * Each group is rendered with its own column width so short action names and
+ * long option flags both stay tightly aligned.
+ */
+function printCommandHelp(spec, version) {
+    const title = version
+        ? `🐎 ExpressoTS CLI v${version}`
+        : "🐎 ExpressoTS CLI";
+    const lines = [
+        "",
+        chalk_1.default.bold.green(title),
+        "",
+        `${chalk_1.default.bold("Usage:")} ${spec.usage}`,
+        "",
+        spec.description,
+    ];
+    if (spec.aliases && spec.aliases.length > 0) {
+        lines.push("", `${chalk_1.default.bold("Aliases:")} ${spec.aliases
+            .map((a) => chalk_1.default.green(a))
+            .join(", ")}`);
+    }
+    // Render each group independently so columns stay tight per-section.
+    for (const group of spec.groups) {
+        lines.push(...(0, render_1.renderHelpGroups)([group]));
+    }
+    if (spec.notes && spec.notes.length > 0) {
+        lines.push("");
+        for (const note of spec.notes) {
+            lines.push(chalk_1.default.dim(note));
+        }
+    }
+    lines.push("", chalk_1.default.dim("Global: -h, --help · -V, --version"), "", `📝  ${chalk_1.default.dim("Docs:")} ${chalk_1.default.green(spec.docs ?? DEFAULT_DOCS)}`, "");
+    process_1.stdout.write(`${lines.join("\n")}\n`);
+}
+exports.printCommandHelp = printCommandHelp;