zudojs-cli 1.2.0 → 2.0.0

package/README.md

@@ -93,6 +93,16 @@ allows esbuild's build script, which pnpm 10+ would otherwise refuse to run.
 - **Fullstack + microservice:** the gateway and services are written at
   `apps/gateway` and `apps/services/<name>`, next to `apps/web`, and are part
   of the root workspace.
+- **Capabilities:** `--capabilities cqrs,events,messaging,queue,observability,openapi,database,security`
+  picks what the project is wired with. The interactive prompt starts from
+  the same list, so both ways of running `create` can produce the same
+  project. Without the flag, a non-interactive run enables `cqrs`,
+  `messaging`, `observability`, `openapi` and `database`.
+- **Failed installs fail the command.** If dependency installation fails,
+  `create` keeps the generated project, prints the command to retry with and
+  exits non-zero, so CI cannot go green with no `node_modules`.
+- **Ctrl-C** during `create` removes the half-written project and exits with
+  status 130.
 
 ### Generating code
 
@@ -102,12 +112,36 @@ subclass), exports it from the modules barrel and registers it in `app.ts`.
 change, and lists those files; pass `--force` to overwrite them. Barrels are
 only appended to. `--dry-run` lists the files without writing anything.
 
+It can be run from any directory inside the project: the project root is
+found by walking up, and everything is generated relative to that root.
+Outside a Zudojs project the command fails instead of writing files into the
+current directory.
+
+**Schematics:** `service`, `module`, `command`, `query`, `controller`,
+`repository`, `middleware`, `event`, `job`, `route`, `model`, `dto`,
+`validator`.
+
+**Options:**
+
+| Option            | Applies to                    | Description                                                        |
+| ----------------- | ----------------------------- | ------------------------------------------------------------------ |
+| `--module <name>` | every schematic but `module`  | Generates inside `<root>/modules/<name>` instead of the schematic's default directory |
+| `--service <name>`| microservice projects, CQRS   | Selects the app a schematic belongs to; also names the CQRS service for `command`/`query` |
+| `--dry-run`       | all                           | Lists the files without writing anything                           |
+| `--force`         | all                           | Overwrites files that already exist                                |
+
+Where a schematic lands depends on the architecture: a `monolith` puts
+services in `src/services` and modules in `src/modules`; a
+`modular-monolith` has modules only, so `generate service` there generates a
+module; in a `microservice` project a schematic goes to the gateway app, or
+to `apps/services/<name>` with `--service <name>`.
+
 ## Commands
 
 | Command    | Description                                                              |
 | ---------- | ------------------------------------------------------------------------ |
 | `create`   | Scaffold a new project (backend, frontend, or fullstack)                 |
-| `generate` | Generate files (service, module, command, query, controller, repository) |
+| `generate` | Generate files — see the schematics below                                |
 | `add`      | Add feature packages (database, queue, messaging, etc.); `--service` targets one microservice app |
 | `dev`      | Start development servers through the project's package manager (`pnpm run dev`, …) |
 | `build`    | Build the project with its detected package manager                      |

package/dist/src/adapters/frontend/flutter.adapter.d.ts

@@ -12,6 +12,15 @@ export declare class FlutterAdapter implements FrontendAdapter {
     readonly framework = "flutter";
     isAvailable(): Promise<boolean>;
     getLatestVersion(): Promise<string>;
+    /**
+     * Converts a project name to a Flutter package name.
+     *
+     * `flutter create --project-name` only accepts lower_snake_case (a valid
+     * Dart package identifier), while `zudojs create` accepts uppercase and
+     * hyphens. Passing the raw name made `flutter create` fail outright, and
+     * this adapter has no fallback template, so the whole run was rolled back.
+     */
+    static toFlutterProjectName(name: string): string;
     scaffold(context: FrontendGenerationContext): Promise<void>;
     getDependencies(context: FrontendGenerationContext): readonly DependencyRequirement[];
     applyZudojsStructure(context: FrontendGenerationContext): Promise<void>;

package/dist/src/adapters/frontend/flutter.adapter.js

@@ -5,6 +5,7 @@
  */
 import { execCommand } from "../../utils/utils.exec.js";
 import { writeFileTree } from "../../utils/utils.fileSystem.js";
+import { normalizeName } from "../../utils/utils.name.js";
 /**
  * Flutter adapter for mobile applications.
  */
@@ -23,6 +24,20 @@ export class FlutterAdapter {
     async getLatestVersion() {
         return "3";
     }
+    /**
+     * Converts a project name to a Flutter package name.
+     *
+     * `flutter create --project-name` only accepts lower_snake_case (a valid
+     * Dart package identifier), while `zudojs create` accepts uppercase and
+     * hyphens. Passing the raw name made `flutter create` fail outright, and
+     * this adapter has no fallback template, so the whole run was rolled back.
+     */
+    static toFlutterProjectName(name) {
+        const snake = normalizeName(name).replace(/-/g, "_");
+        if (snake === "")
+            return "zudojs_app";
+        return /^[0-9]/.test(snake) ? `app_${snake}` : snake;
+    }
     async scaffold(context) {
         const { projectPath } = context;
         const org = "com.zudojs";
@@ -32,7 +47,7 @@ export class FlutterAdapter {
             "--org",
             org,
             "--project-name",
-            context.project.name,
+            FlutterAdapter.toFlutterProjectName(context.project.name),
             "--platforms",
             "android,ios,web",
         ], projectPath);

package/dist/src/bin/zudojs.js

@@ -6,7 +6,8 @@
  */
 import { createCLI } from "../cliApplication/index.js";
 import { createCommand } from "../cliCommand/index.js";
-import { CLI_VERSION, FEATURE_PACKAGES } from "../constants/index.js";
+import { CLI_VERSION, FEATURE_NAMES, SCHEMATIC_NAMES, } from "../constants/index.js";
+import { CLI_NAME } from "../cliConstant/cliConstant.value.js";
 import { runCreateCommand } from "../commands/create.command.js";
 import { runDevCommand } from "../commands/dev.command.js";
 import { runGenerateCommand } from "../commands/generate.command.js";
@@ -15,7 +16,8 @@ import { runBuildCommand } from "../commands/build.command.js";
 import { runDoctorCommand } from "../commands/doctor.command.js";
 import { runInfoCommand } from "../commands/info.command.js";
 const app = createCLI({
-    name: "Zudojs",
+    // The name the help output tells people to type, so it must be the binary.
+    name: CLI_NAME,
     // Read from the CLI's own package.json, so `zudojs --version` cannot
     // drift from the published version.
     version: CLI_VERSION,
@@ -108,6 +110,15 @@ app.register(createCommand({
             description: "Comma-separated service names (microservice architecture only)",
             type: "string",
         },
+        {
+            // No default. An absent flag keeps the non-interactive branch's
+            // historical set (cqrs, messaging, observability, openapi, database)
+            // and seeds the interactive prompt with nothing, so adding the flag
+            // does not change what an existing command line produces.
+            name: "capabilities",
+            description: "Comma-separated capabilities (cqrs, events, messaging, queue, observability, openapi, database, security)",
+            type: "string",
+        },
     ],
     execute: async (context) => {
         await runCreateCommand(context);
@@ -148,7 +159,7 @@ app.register(createCommand({
     arguments: [
         {
             name: "schematic",
-            description: "The schematic to generate (service, module, command, query, controller, repository)",
+            description: `The schematic to generate (${SCHEMATIC_NAMES.join(", ")})`,
             required: true,
         },
         {
@@ -167,7 +178,7 @@ app.register(createCommand({
         {
             name: "module",
             short: "m",
-            description: "The module name",
+            description: "The module a generated file belongs to (modular monolith), e.g. --module billing",
             type: "string",
         },
         {
@@ -193,7 +204,7 @@ app.register(createCommand({
     arguments: [
         {
             name: "feature",
-            description: `The feature to add (${Object.keys(FEATURE_PACKAGES).join(", ")})`,
+            description: `The feature to add (${FEATURE_NAMES.join(", ")})`,
             required: true,
         },
     ],

package/dist/src/cliApplication/cliApplication.builtins.d.ts

@@ -4,6 +4,10 @@
  * Help and version request detection and output.
  */
 import type { CLIArguments, CLIWriter } from "../cliType/cliType.type.js";
+/** Returns whether a single token is a help flag (`-h` or `--help`). */
+export declare function isHelpFlag(token: string): boolean;
+/** Returns whether a single token is a version flag (`-v` or `--version`). */
+export declare function isVersionFlag(token: string): boolean;
 /**
  * Returns whether the args are a help request.
  *

package/dist/src/cliApplication/cliApplication.builtins.js

@@ -3,7 +3,15 @@
  *
  * Help and version request detection and output.
  */
-import { CLI_COMMANDS, CLI_DEFAULTS, } from "../cliConstant/cliConstant.value.js";
+import { CLI_ALIASES, CLI_COMMANDS, CLI_DEFAULTS, CLI_FORMAT, CLI_HELP, CLI_SYMBOLS, } from "../cliConstant/cliConstant.value.js";
+/** Returns whether a single token is a help flag (`-h` or `--help`). */
+export function isHelpFlag(token) {
+    return CLI_ALIASES.HELP.includes(token);
+}
+/** Returns whether a single token is a version flag (`-v` or `--version`). */
+export function isVersionFlag(token) {
+    return CLI_ALIASES.VERSION.includes(token);
+}
 /**
  * Returns whether the args are a help request.
  *
@@ -12,7 +20,9 @@ import { CLI_COMMANDS, CLI_DEFAULTS, } from "../cliConstant/cliConstant.value.js
  */
 export function isHelpRequest(args) {
     const first = args[0];
-    return first === CLI_COMMANDS.HELP || first === "-h" || first === "--help";
+    if (first === undefined)
+        return false;
+    return first === CLI_COMMANDS.HELP || isHelpFlag(first);
 }
 /**
  * Returns whether the args are a version request.
@@ -21,7 +31,9 @@ export function isHelpRequest(args) {
  */
 export function isVersionRequest(args) {
     const first = args[0];
-    return (first === CLI_COMMANDS.VERSION || first === "-v" || first === "--version");
+    if (first === undefined)
+        return false;
+    return first === CLI_COMMANDS.VERSION || isVersionFlag(first);
 }
 /** Prints the version string. */
 export function printVersion(writer, version) {
@@ -33,18 +45,25 @@ export function printHelp(writer, name, version, description, commands = []) {
     lines.push(`${name} ${version ? `v${version}` : ""}`.trim());
     if (description)
         lines.push(description);
-    lines.push("", "Usage:", `  ${name} <command> [options]`, "", "Commands:");
+    lines.push(CLI_FORMAT.EMPTY, CLI_HELP.USAGE, `${CLI_FORMAT.INDENT}${name} <${CLI_SYMBOLS.COMMAND}> [${CLI_SYMBOLS.OPTION}s]`, CLI_FORMAT.EMPTY, CLI_HELP.COMMANDS);
     const sorted = commands.slice().sort((a, b) => a.name.localeCompare(b.name));
     if (sorted.length === 0) {
-        lines.push("  No commands registered.");
+        lines.push(`${CLI_FORMAT.INDENT}No commands registered.`);
     }
     else {
+        const width = sorted.reduce((max, cmd) => Math.max(max, formatCommandTerm(cmd).length), 0);
         for (const cmd of sorted) {
-            const aliases = cmd.aliases?.length ? ` (${cmd.aliases.join(", ")})` : "";
-            lines.push(`  ${cmd.name}${aliases}${cmd.description ? `  ${cmd.description}` : ""}`);
+            const term = formatCommandTerm(cmd).padEnd(width);
+            lines.push(`${CLI_FORMAT.INDENT}${term}${cmd.description ? `${CLI_FORMAT.INDENT}${cmd.description}` : ""}`.trimEnd());
         }
     }
-    lines.push("", "Options:", "  -h, --help     Show help.", "  -v, --version  Show version.");
-    writer.writeLine(lines.join("\n"));
+    lines.push(CLI_FORMAT.EMPTY, CLI_HELP.OPTIONS, `${CLI_FORMAT.INDENT}-h, --help     Show help.`, `${CLI_FORMAT.INDENT}-v, --version  Show version.`, CLI_FORMAT.EMPTY, `Run "${name} ${CLI_COMMANDS.HELP} <${CLI_SYMBOLS.COMMAND}>" for help on one ${CLI_SYMBOLS.COMMAND}.`);
+    writer.writeLine(lines.join(CLI_FORMAT.NEWLINE));
+}
+/** Renders a command's name and aliases for the command list. */
+function formatCommandTerm(cmd) {
+    return cmd.aliases?.length
+        ? `${cmd.name} (${cmd.aliases.join(", ")})`
+        : cmd.name;
 }
 //# sourceMappingURL=cliApplication.builtins.js.map

package/dist/src/cliApplication/cliApplication.core.d.ts

@@ -32,6 +32,14 @@ export declare class ZudojsCLI implements CLIApplication {
     use(hooks: CLIHooks): this;
     /** Runs the CLI application. */
     run(args?: CLIArguments): Promise<number>;
+    private printApplicationHelp;
+    /**
+     * Resolves the command named after a help request, if any.
+     *
+     * Throws when a name is given that is not registered, so `zudojs help
+     * bogus` says so instead of silently printing the global help.
+     */
+    private resolveHelpTarget;
     private findCommand;
     private getCommandArguments;
     private createContext;

package/dist/src/cliApplication/cliApplication.core.js

@@ -4,15 +4,17 @@
  * Main CLI application class that orchestrates command registration,
  * parsing, execution, and built-in help/version handling.
  */
-import { CLI_DEFAULTS, CLI_EXIT_CODES, } from "../cliConstant/cliConstant.value.js";
+import { CLI_DEFAULTS, CLI_EXIT_CODES, CLI_MESSAGES, CLI_OPTION_PREFIXES, } from "../cliConstant/cliConstant.value.js";
 import { CLIExecutionError, normalizeCLIError } from "../cliError/index.js";
 import { CommandNotFoundError } from "../cliError/cliError.command.js";
+import { InvalidArgumentsError } from "../cliError/cliError.argument.js";
 import { CLICommandRegistry } from "../cliCommand/cliCommand.registry.js";
 import { executeCommand } from "../cliCommand/cliCommand.factory.js";
 import { CLIParser, resolveCommand } from "../cliParser/index.js";
 import { createCLIWriter } from "./cliApplication.writer.js";
 import { createCLILogger } from "./cliApplication.logger.js";
-import { isHelpRequest, isVersionRequest, printVersion, printHelp, } from "./cliApplication.builtins.js";
+import { isHelpFlag, isHelpRequest, isVersionRequest, printVersion, printHelp, } from "./cliApplication.builtins.js";
+import { printCommandHelp } from "./cliApplication.help.js";
 /* -------------------------------------------------------------------------- */
 /* Application                                                                */
 /* -------------------------------------------------------------------------- */
@@ -72,7 +74,13 @@ export class ZudojsCLI {
         this.running = true;
         try {
             if (isHelpRequest(args)) {
-                printHelp(this.writer, this.name, this.version, this.description, this.commands.list());
+                // `zudojs help create` and `zudojs --help create` name a command.
+                const target = this.resolveHelpTarget(args);
+                if (target) {
+                    printCommandHelp(this.writer, this.name, target);
+                    return CLI_EXIT_CODES.SUCCESS;
+                }
+                this.printApplicationHelp();
                 return CLI_EXIT_CODES.SUCCESS;
             }
             if (isVersionRequest(args)) {
@@ -82,12 +90,24 @@ export class ZudojsCLI {
             const command = this.findCommand(args);
             if (!command) {
                 if (args.length === 0) {
-                    printHelp(this.writer, this.name, this.version, this.description, this.commands.list());
+                    this.printApplicationHelp();
                     return CLI_EXIT_CODES.SUCCESS;
                 }
-                throw new CommandNotFoundError(String(args[0]));
+                const first = String(args[0]);
+                // `findCommand` skips flag-shaped tokens, so a lone `-vh` would
+                // otherwise be reported as a command named "-vh".
+                if (first.startsWith(CLI_OPTION_PREFIXES.SHORT)) {
+                    throw new InvalidArgumentsError(CLI_MESSAGES.MISSING_COMMAND);
+                }
+                throw new CommandNotFoundError(first);
             }
             const commandArgs = this.getCommandArguments(args, command);
+            // Checked before parsing: `--help` is not a declared option, so the
+            // parser would reject it as invalid and exit 2.
+            if (commandArgs.some(isHelpFlag)) {
+                printCommandHelp(this.writer, this.name, command);
+                return CLI_EXIT_CODES.SUCCESS;
+            }
             const commandContext = this.createContext(commandArgs, command);
             if (this.hooks.beforeRun) {
                 await this.hooks.beforeRun(commandContext);
@@ -131,6 +151,26 @@ export class ZudojsCLI {
         }
     }
     /* ---- Internal ---- */
+    printApplicationHelp() {
+        printHelp(this.writer, this.name, this.version, this.description, this.commands.list());
+    }
+    /**
+     * Resolves the command named after a help request, if any.
+     *
+     * Throws when a name is given that is not registered, so `zudojs help
+     * bogus` says so instead of silently printing the global help.
+     */
+    resolveHelpTarget(args) {
+        const target = args
+            .slice(1)
+            .find((arg) => !arg.startsWith(CLI_OPTION_PREFIXES.SHORT));
+        if (target === undefined)
+            return undefined;
+        const command = resolveCommand(this.commands.list(), target);
+        if (!command)
+            throw new CommandNotFoundError(target);
+        return command;
+    }
     findCommand(args) {
         for (const arg of args) {
             if (arg.startsWith("-"))

package/dist/src/cliApplication/cliApplication.help.d.ts

@@ -0,0 +1,17 @@
+/**
+ * zudojs-cli — Command Help
+ *
+ * Renders the help block for one command: its usage line, aliases,
+ * positional arguments and options, with shorts and defaults.
+ */
+import type { CLICommand, CLIWriter } from "../cliType/cliType.type.js";
+/**
+ * Prints the help block for a single command.
+ *
+ * Reached by `zudojs <command> --help`, `zudojs <command> -h` and
+ * `zudojs help <command>`. The first two used to be handed to the parser,
+ * which rejected `--help` as an undeclared option and exited 2, so no
+ * command's flags could be discovered from the CLI.
+ */
+export declare function printCommandHelp(writer: CLIWriter, applicationName: string, command: CLICommand): void;
+//# sourceMappingURL=cliApplication.help.d.ts.map

package/dist/src/cliApplication/cliApplication.help.js

@@ -0,0 +1,94 @@
+/**
+ * zudojs-cli — Command Help
+ *
+ * Renders the help block for one command: its usage line, aliases,
+ * positional arguments and options, with shorts and defaults.
+ */
+import { CLI_FORMAT, CLI_HELP, CLI_OPTION_PREFIXES, CLI_SYMBOLS, } from "../cliConstant/cliConstant.value.js";
+/* -------------------------------------------------------------------------- */
+/* Formatting                                                                 */
+/* -------------------------------------------------------------------------- */
+/** Renders one positional as it appears in the usage line. */
+function formatArgumentToken(argument) {
+    const name = argument.variadic ? `${argument.name}...` : argument.name;
+    return argument.required ? `<${name}>` : `[<${name}>]`;
+}
+/** Renders the flag column of one option, e.g. `-t, --type <string>`. */
+function formatOptionFlags(option) {
+    const short = option.short
+        ? `${CLI_OPTION_PREFIXES.SHORT}${option.short}, `
+        : "";
+    const long = `${CLI_OPTION_PREFIXES.LONG}${option.name}`;
+    const placeholder = option.type === "boolean" ? "" : ` <${option.type ?? "string"}>`;
+    return `${short}${long}${placeholder}`;
+}
+/** Renders the description column of one option. */
+function formatOptionDescription(option) {
+    const parts = [];
+    if (option.description)
+        parts.push(option.description);
+    if (option.defaultValue !== undefined) {
+        parts.push(`(default: ${String(option.defaultValue)})`);
+    }
+    return parts.join(" ");
+}
+/** Renders `<term>  <description>` rows on a common column. */
+function formatRows(rows) {
+    const width = rows.reduce((max, [term]) => Math.max(max, term.length), 0);
+    return rows.map(([term, description]) => description
+        ? `${CLI_FORMAT.INDENT}${term.padEnd(width)}${CLI_FORMAT.INDENT}${description}`
+        : `${CLI_FORMAT.INDENT}${term}`);
+}
+/* -------------------------------------------------------------------------- */
+/* Command Help                                                               */
+/* -------------------------------------------------------------------------- */
+/**
+ * Prints the help block for a single command.
+ *
+ * Reached by `zudojs <command> --help`, `zudojs <command> -h` and
+ * `zudojs help <command>`. The first two used to be handed to the parser,
+ * which rejected `--help` as an undeclared option and exited 2, so no
+ * command's flags could be discovered from the CLI.
+ */
+export function printCommandHelp(writer, applicationName, command) {
+    const args = command.arguments ?? [];
+    const options = command.options ?? [];
+    const lines = [];
+    const usage = [
+        applicationName,
+        command.name,
+        ...args.map(formatArgumentToken),
+        `[${CLI_SYMBOLS.OPTION}s]`,
+    ].join(" ");
+    lines.push(CLI_HELP.USAGE, `${CLI_FORMAT.INDENT}${usage}`);
+    if (command.description) {
+        lines.push(CLI_FORMAT.EMPTY, CLI_HELP.DESCRIPTION, `${CLI_FORMAT.INDENT}${command.description}`);
+    }
+    if (command.aliases?.length) {
+        lines.push(CLI_FORMAT.EMPTY, CLI_HELP.ALIASES, `${CLI_FORMAT.INDENT}${command.aliases.join(", ")}`);
+    }
+    lines.push(CLI_FORMAT.EMPTY, CLI_HELP.ARGUMENTS);
+    if (args.length === 0) {
+        lines.push(`${CLI_FORMAT.INDENT}None — this ${CLI_SYMBOLS.COMMAND} takes no positional ${CLI_SYMBOLS.ARGUMENT}s.`);
+    }
+    else {
+        lines.push(...formatRows(args.map((argument) => [
+            formatArgumentToken(argument),
+            [
+                argument.description ?? "",
+                argument.defaultValue !== undefined
+                    ? `(default: ${String(argument.defaultValue)})`
+                    : "",
+            ]
+                .filter(Boolean)
+                .join(" "),
+        ])));
+    }
+    lines.push(CLI_FORMAT.EMPTY, CLI_HELP.OPTIONS);
+    lines.push(...formatRows([
+        ...options.map((option) => [formatOptionFlags(option), formatOptionDescription(option)]),
+        ["-h, --help", `Show help for this ${CLI_SYMBOLS.COMMAND}.`],
+    ]));
+    writer.writeLine(lines.join(CLI_FORMAT.NEWLINE));
+}
+//# sourceMappingURL=cliApplication.help.js.map

package/dist/src/cliApplication/cliApplication.logger.js

@@ -14,6 +14,7 @@
  * @module cliApplication/logger
  */
 import { createLogger, LoggerLevel, } from "@zudojs/logger";
+import { CLI_ENVIRONMENT, CLI_NAME } from "../cliConstant/cliConstant.value.js";
 /** Renders one entry as the single line the user sees. */
 export function formatCLILogLine(entry) {
     switch (entry.levelName) {
@@ -31,14 +32,13 @@ export function formatCLILogLine(entry) {
 }
 /** Creates the logger handed to every command as `context.logger`. */
 export function createCLILogger(options = {}) {
+    const debug = process.env[CLI_ENVIRONMENT.DEBUG];
     const verbose = options.verbose ??
-        (process.env["ZUDOJS_DEBUG"] !== undefined &&
-            process.env["ZUDOJS_DEBUG"] !== "" &&
-            process.env["ZUDOJS_DEBUG"] !== "0");
+        (debug !== undefined && debug !== "" && debug !== "0");
     const stdout = options.stdout ?? ((line) => process.stdout.write(`${line}\n`));
     const stderr = options.stderr ?? ((line) => process.stderr.write(`${line}\n`));
     return createLogger({
-        name: "zudojs",
+        name: CLI_NAME,
         level: verbose ? LoggerLevel.TRACE : LoggerLevel.INFO,
         // Writes must complete before a command returns; `process.exit` follows
         // an error immediately.

package/dist/src/cliCommand/cliCommand.validator.js

@@ -3,7 +3,9 @@
  *
  * Validation logic and utility functions for CLI commands.
  */
+import { CLI_LIMITS } from "../cliConstant/cliConstant.value.js";
 import { InvalidCommandNameError, DuplicateCommandError, } from "../cliError/cliError.command.js";
+import { InvalidOptionNameError } from "../cliError/cliError.option.js";
 /* -------------------------------------------------------------------------- */
 /* Validation                                                                 */
 /* -------------------------------------------------------------------------- */
@@ -18,10 +20,27 @@ export function validateCommand(command) {
     if (!/^[a-zA-Z0-9][a-zA-Z0-9:_-]*$/.test(command.name.trim())) {
         throw new InvalidCommandNameError(command.name);
     }
+    if (command.name.trim().length > CLI_LIMITS.MAX_COMMAND_NAME_LENGTH) {
+        throw new InvalidCommandNameError(command.name);
+    }
     if (command.description !== undefined &&
         typeof command.description !== "string") {
         throw new TypeError(`Description for command "${command.name}" must be a string.`);
     }
+    if (command.description !== undefined &&
+        command.description.length > CLI_LIMITS.MAX_DESCRIPTION_LENGTH) {
+        throw new TypeError(`Description for command "${command.name}" exceeds ${CLI_LIMITS.MAX_DESCRIPTION_LENGTH} characters.`);
+    }
+    for (const option of command.options ?? []) {
+        if (option.name.length > CLI_LIMITS.MAX_OPTION_NAME_LENGTH) {
+            throw new InvalidOptionNameError(option.name);
+        }
+    }
+    for (const argument of command.arguments ?? []) {
+        if (argument.name.length > CLI_LIMITS.MAX_ARGUMENT_NAME_LENGTH) {
+            throw new InvalidCommandNameError(argument.name);
+        }
+    }
     if (command.aliases) {
         const seen = new Set();
         for (const alias of command.aliases) {
@@ -29,6 +48,9 @@ export function validateCommand(command) {
                 throw new InvalidCommandNameError(String(alias));
             }
             const normalized = alias.trim();
+            if (normalized.length > CLI_LIMITS.MAX_ALIAS_LENGTH) {
+                throw new InvalidCommandNameError(normalized);
+            }
             if (normalized === command.name.trim()) {
                 throw new DuplicateCommandError(normalized);
             }

package/dist/src/cliConstant/cliConstant.value.d.ts

@@ -14,6 +14,14 @@ export declare const CLI_DEFAULTS: {
     readonly DEFAULT_CWD: string;
     readonly EXIT_CODE: 0;
 };
+/** Internal symbolic names for CLI elements. */
+export declare const CLI_SYMBOLS: {
+    readonly COMMAND: "command";
+    readonly OPTION: "option";
+    readonly ARGUMENT: "argument";
+    readonly HELP: "help";
+    readonly VERSION: "version";
+};
 /** Built-in command names. */
 export declare const CLI_COMMANDS: {
     readonly HELP: "help";
@@ -30,14 +38,6 @@ export declare const CLI_OPTION_PREFIXES: {
     readonly LONG: "--";
     readonly VALUE_SEPARATOR: "=";
 };
-/** Internal symbolic names for CLI elements. */
-export declare const CLI_SYMBOLS: {
-    readonly COMMAND: "command";
-    readonly OPTION: "option";
-    readonly ARGUMENT: "argument";
-    readonly HELP: "help";
-    readonly VERSION: "version";
-};
 /** Standard CLI messages. */
 export declare const CLI_MESSAGES: {
     readonly COMMAND_NOT_FOUND: "Command not found.";
@@ -45,7 +45,7 @@ export declare const CLI_MESSAGES: {
     readonly PERMISSION_DENIED: "Permission denied.";
     readonly INTERRUPTED: "Process interrupted.";
     readonly UNKNOWN_ERROR: "An unexpected error occurred.";
-    readonly MISSING_COMMAND: "A command is required.";
+    readonly MISSING_COMMAND: "No command given.";
 };
 /** Labels used in help output. */
 export declare const CLI_HELP: {
@@ -57,11 +57,17 @@ export declare const CLI_HELP: {
     readonly DESCRIPTION: "Description:";
     readonly EXAMPLES: "Examples:";
 };
-/** Environment variable names. */
+/**
+ * Environment variable names the CLI reads.
+ *
+ * Every entry has a single reader: `DEBUG` turns on verbose logging,
+ * `CI` and `NO_UPDATE_CHECK`/`NPM_OFFLINE` suppress the update check.
+ */
 export declare const CLI_ENVIRONMENT: {
-    readonly NODE_ENV: "NODE_ENV";
-    readonly DEBUG: "DEBUG";
+    readonly DEBUG: "ZUDOJS_DEBUG";
     readonly CI: "CI";
+    readonly NO_UPDATE_CHECK: "ZUDOJS_NO_UPDATE_CHECK";
+    readonly NPM_OFFLINE: "npm_config_offline";
 };
 /** Formatting constants. */
 export declare const CLI_FORMAT: {