zudojs-cli 1.2.0 → 2.0.0

package/dist/src/cliConstant/cliConstant.value.js

@@ -11,20 +11,31 @@ import { CLI_VERSION } from "./cliVersion.js";
 export const CLI_NAME = "zudojs";
 /** Default application configuration. */
 export const CLI_DEFAULTS = {
-    NAME: "zudojs",
+    NAME: CLI_NAME,
     VERSION: CLI_VERSION,
     DESCRIPTION: "Command-line interface for the Zudojs framework.",
-    COMMAND_PREFIX: "zudojs",
+    COMMAND_PREFIX: CLI_NAME,
     DEFAULT_CWD: process.cwd(),
     EXIT_CODE: 0,
 };
 /* -------------------------------------------------------------------------- */
+/* Symbolic Names                                                             */
+/* -------------------------------------------------------------------------- */
+/** Internal symbolic names for CLI elements. */
+export const CLI_SYMBOLS = {
+    COMMAND: "command",
+    OPTION: "option",
+    ARGUMENT: "argument",
+    HELP: "help",
+    VERSION: "version",
+};
+/* -------------------------------------------------------------------------- */
 /* Built-in Commands                                                          */
 /* -------------------------------------------------------------------------- */
 /** Built-in command names. */
 export const CLI_COMMANDS = {
-    HELP: "help",
-    VERSION: "version",
+    HELP: CLI_SYMBOLS.HELP,
+    VERSION: CLI_SYMBOLS.VERSION,
 };
 /** Built-in command aliases. */
 export const CLI_ALIASES = {
@@ -41,17 +52,6 @@ export const CLI_OPTION_PREFIXES = {
     VALUE_SEPARATOR: "=",
 };
 /* -------------------------------------------------------------------------- */
-/* Symbolic Names                                                             */
-/* -------------------------------------------------------------------------- */
-/** Internal symbolic names for CLI elements. */
-export const CLI_SYMBOLS = {
-    COMMAND: "command",
-    OPTION: "option",
-    ARGUMENT: "argument",
-    HELP: "help",
-    VERSION: "version",
-};
-/* -------------------------------------------------------------------------- */
 /* User-Facing Messages                                                       */
 /* -------------------------------------------------------------------------- */
 /** Standard CLI messages. */
@@ -61,7 +61,7 @@ export const CLI_MESSAGES = {
     PERMISSION_DENIED: "Permission denied.",
     INTERRUPTED: "Process interrupted.",
     UNKNOWN_ERROR: "An unexpected error occurred.",
-    MISSING_COMMAND: "A command is required.",
+    MISSING_COMMAND: "No command given.",
 };
 /* -------------------------------------------------------------------------- */
 /* Help Labels                                                                */
@@ -79,11 +79,17 @@ export const CLI_HELP = {
 /* -------------------------------------------------------------------------- */
 /* Environment                                                                */
 /* -------------------------------------------------------------------------- */
-/** 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 const CLI_ENVIRONMENT = {
-    NODE_ENV: "NODE_ENV",
-    DEBUG: "DEBUG",
+    DEBUG: "ZUDOJS_DEBUG",
     CI: "CI",
+    NO_UPDATE_CHECK: "ZUDOJS_NO_UPDATE_CHECK",
+    NPM_OFFLINE: "npm_config_offline",
 };
 /* -------------------------------------------------------------------------- */
 /* Formatting                                                                 */

package/dist/src/cliError/cliError.argument.js

@@ -4,7 +4,7 @@
  * Error classes for argument validation failures.
  */
 import { CLIError } from "./cliError.base.js";
-import { CLI_ERROR_CODES, CLI_EXIT_CODES, } from "../cliConstant/cliConstant.value.js";
+import { CLI_ERROR_CODES, CLI_EXIT_CODES, CLI_MESSAGES, } from "../cliConstant/cliConstant.value.js";
 /* -------------------------------------------------------------------------- */
 /* Invalid Arguments                                                          */
 /* -------------------------------------------------------------------------- */
@@ -12,7 +12,7 @@ import { CLI_ERROR_CODES, CLI_EXIT_CODES, } from "../cliConstant/cliConstant.val
  * Thrown when command arguments fail validation.
  */
 export class InvalidArgumentsError extends CLIError {
-    constructor(message = "Invalid command arguments.", options = {}) {
+    constructor(message = CLI_MESSAGES.INVALID_ARGUMENTS, options = {}) {
         super(message, {
             ...options,
             code: CLI_ERROR_CODES.INVALID_ARGUMENTS,

package/dist/src/cliError/cliError.base.js

@@ -6,7 +6,7 @@
  * command, option, argument).
  */
 import { ApplicationError } from "@zudojs/errors";
-import { CLI_ERROR_CODES, CLI_EXIT_CODES, } from "../cliConstant/cliConstant.value.js";
+import { CLI_ERROR_CODES, CLI_EXIT_CODES, CLI_MESSAGES, } from "../cliConstant/cliConstant.value.js";
 /**
  * Base error for all CLI subsystem failures.
  *
@@ -54,21 +54,44 @@ export class CLIError extends ApplicationError {
 export function isCLIError(error) {
     return error instanceof CLIError;
 }
+/**
+ * Reads a process exit code carried by an arbitrary error.
+ *
+ * Only `CLIError` extends this base class; `CommandNotFoundError`,
+ * `CLIPermissionError` and the other errors built on `@zudojs/errors`
+ * declare their own `exitCode` field. Without this, every one of them was
+ * re-wrapped as `GENERAL_ERROR` and the declared `COMMAND_NOT_FOUND` (3),
+ * `PERMISSION_DENIED` (4) and `INTERRUPTED` (130) codes never reached the
+ * shell.
+ */
+function readExitCode(error) {
+    if (typeof error !== "object" || error === null)
+        return undefined;
+    const candidate = error.exitCode;
+    if (typeof candidate !== "number" ||
+        !Number.isInteger(candidate) ||
+        candidate < 0 ||
+        candidate > 255) {
+        return undefined;
+    }
+    return candidate;
+}
 /** Normalizes any error into a CLIError. */
-export function normalizeCLIError(error, fallbackMessage = "An unexpected CLI error occurred.") {
+export function normalizeCLIError(error, fallbackMessage = CLI_MESSAGES.UNKNOWN_ERROR) {
     if (error instanceof CLIError) {
         return error;
     }
+    const exitCode = readExitCode(error) ?? CLI_EXIT_CODES.GENERAL_ERROR;
     if (error instanceof Error) {
         return new CLIError(error.message || fallbackMessage, {
             code: CLI_ERROR_CODES.UNKNOWN_ERROR,
-            exitCode: CLI_EXIT_CODES.GENERAL_ERROR,
+            exitCode,
             cause: error,
         });
     }
     return new CLIError(fallbackMessage, {
         code: CLI_ERROR_CODES.UNKNOWN_ERROR,
-        exitCode: CLI_EXIT_CODES.GENERAL_ERROR,
+        exitCode,
         cause: error,
     });
 }
@@ -77,7 +100,7 @@ export function getCLIExitCode(error) {
     if (isCLIError(error)) {
         return error.exitCode;
     }
-    return CLI_EXIT_CODES.GENERAL_ERROR;
+    return readExitCode(error) ?? CLI_EXIT_CODES.GENERAL_ERROR;
 }
 /** Extracts the error code from an error. */
 export function getCLIErrorCode(error) {

package/dist/src/cliError/cliError.command.js

@@ -5,7 +5,7 @@
  * Extends base errors from `@zudojs/errors` where possible.
  */
 import { NotFoundError, ConflictError } from "@zudojs/errors";
-import { CLI_ERROR_CODES, CLI_EXIT_CODES, } from "../cliConstant/cliConstant.value.js";
+import { CLI_ERROR_CODES, CLI_EXIT_CODES, CLI_MESSAGES, } from "../cliConstant/cliConstant.value.js";
 /* -------------------------------------------------------------------------- */
 /* Command Not Found                                                          */
 /* -------------------------------------------------------------------------- */
@@ -16,7 +16,10 @@ import { CLI_ERROR_CODES, CLI_EXIT_CODES, } from "../cliConstant/cliConstant.val
 export class CommandNotFoundError extends NotFoundError {
     exitCode;
     constructor(command) {
-        super(`Command "${command}" was not found.`, {
+        const message = command
+            ? `Command "${command}" was not found.`
+            : CLI_MESSAGES.COMMAND_NOT_FOUND;
+        super(message, {
             code: CLI_ERROR_CODES.COMMAND_NOT_FOUND,
             statusCode: 404,
             expose: true,

package/dist/src/cliError/cliError.execution.js

@@ -5,7 +5,7 @@
  */
 import { AuthorizationError, ConfigurationError } from "@zudojs/errors";
 import { CLIError } from "./cliError.base.js";
-import { CLI_ERROR_CODES, CLI_EXIT_CODES, } from "../cliConstant/cliConstant.value.js";
+import { CLI_ERROR_CODES, CLI_EXIT_CODES, CLI_MESSAGES, } from "../cliConstant/cliConstant.value.js";
 /* -------------------------------------------------------------------------- */
 /* Execution Error                                                            */
 /* -------------------------------------------------------------------------- */
@@ -32,7 +32,7 @@ export class CLIExecutionError extends CLIError {
  */
 export class CLIPermissionError extends AuthorizationError {
     exitCode;
-    constructor(message = "Permission denied.", options = {}) {
+    constructor(message = CLI_MESSAGES.PERMISSION_DENIED, options = {}) {
         super(message, {
             ...options,
             code: CLI_ERROR_CODES.PERMISSION_DENIED,
@@ -56,7 +56,7 @@ export class CLIPermissionError extends AuthorizationError {
  * Thrown when the CLI process is interrupted (e.g. SIGINT).
  */
 export class CLIInterruptedError extends CLIError {
-    constructor(message = "Process interrupted.", options = {}) {
+    constructor(message = CLI_MESSAGES.INTERRUPTED, options = {}) {
         super(message, {
             ...options,
             code: CLI_ERROR_CODES.INTERRUPTED,

package/dist/src/cliParser/cliParser.core.js

@@ -32,9 +32,13 @@ export class CLIParser {
         const definitions = command?.options ?? [];
         const argumentsDefinitions = command?.arguments ?? [];
         let index = 0;
+        // Where the `--` pass-through began, if it did: everything after it is
+        // deliberately opaque and is never measured against the declarations.
+        let escapedAt;
         while (index < tokens.length) {
             const token = tokens[index];
             if (token === "--") {
+                escapedAt = positional.length;
                 positional.push(...tokens.slice(index + 1));
                 break;
             }
@@ -64,8 +68,13 @@ export class CLIParser {
                 options[definition.name] = definition.defaultValue;
             }
         }
-        const parsedArguments = this.parseArguments(positional, argumentsDefinitions);
-        if (!this.allowUnknownCommands &&
+        // Surplus positionals are only an error once a command is known: with no
+        // command there is no declaration to measure them against.
+        const parsedArguments = this.parseArguments(positional, argumentsDefinitions, command === undefined ? null : (escapedAt ?? positional.length));
+        // `stopAtFirstArgument` is checked here too: without it the fallback undid
+        // the flag, putting the first positional in both `commands` and `args`.
+        if (!this.stopAtFirstArgument &&
+            !this.allowUnknownCommands &&
             !command &&
             commands.length === 0 &&
             tokens.length > 0) {
@@ -82,10 +91,8 @@ export class CLIParser {
         };
     }
     /* ---- Arguments ---- */
-    parseArguments(values, definitions) {
+    parseArguments(values, definitions, strictUpTo) {
         const result = {};
-        if (definitions.length === 0)
-            return result;
         let valueIndex = 0;
         for (const definition of definitions) {
             if (definition.variadic) {
@@ -110,7 +117,9 @@ export class CLIParser {
             result[definition.name] = value;
             valueIndex++;
         }
-        if (valueIndex < values.length) {
+        // Commands that declare no arguments used to return before this check,
+        // so `zudojs doctor my-proj` discarded `my-proj` without a word.
+        if (strictUpTo !== null && valueIndex < strictUpTo) {
             throw new InvalidArgumentsError(`Unexpected argument "${values[valueIndex]}".`);
         }
         return result;

package/dist/src/cliParser/cliParser.helper.d.ts

@@ -15,6 +15,17 @@ export declare function parseBoolean(value: string, option?: string): boolean;
 export declare function isOption(token: string): boolean;
 /** Returns whether a token is a long option (e.g. `--verbose`). */
 export declare function isLongOption(token: string): boolean;
+/** Returns whether a token looks like a negative number (e.g. `-1`, `-2.5`). */
+export declare function isNegativeNumber(token: string): boolean;
+/**
+ * Returns whether the token following an option can be taken as its value.
+ *
+ * A flag-looking token is refused so that `--type --frontend react` reports
+ * the missing value for `--type` instead of setting it to `"--frontend"`.
+ * Negative numbers stay usable for numeric options: `--port -1` and
+ * `--port=-1` both keep working.
+ */
+export declare function isOptionValueToken(definition: CLIOption, token: string | undefined): token is string;
 /** Returns whether a token is a short option (e.g. `-v`). */
 export declare function isShortOption(token: string): boolean;
 /** Resolves a command name to a CLICommand. */

package/dist/src/cliParser/cliParser.helper.js

@@ -54,6 +54,25 @@ export function isLongOption(token) {
     return (token.startsWith(CLI_OPTION_PREFIXES.LONG) &&
         token.length > CLI_OPTION_PREFIXES.LONG.length);
 }
+/** Returns whether a token looks like a negative number (e.g. `-1`, `-2.5`). */
+export function isNegativeNumber(token) {
+    return /^-(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(token);
+}
+/**
+ * Returns whether the token following an option can be taken as its value.
+ *
+ * A flag-looking token is refused so that `--type --frontend react` reports
+ * the missing value for `--type` instead of setting it to `"--frontend"`.
+ * Negative numbers stay usable for numeric options: `--port -1` and
+ * `--port=-1` both keep working.
+ */
+export function isOptionValueToken(definition, token) {
+    if (token === undefined || token === "--")
+        return false;
+    if (!isOption(token))
+        return true;
+    return definition.type === "number" && isNegativeNumber(token);
+}
 /** Returns whether a token is a short option (e.g. `-v`). */
 export function isShortOption(token) {
     return (token.startsWith(CLI_OPTION_PREFIXES.SHORT) &&

package/dist/src/cliParser/cliParser.longOption.js

@@ -5,7 +5,7 @@
  */
 import { CLI_OPTION_PREFIXES } from "../cliConstant/cliConstant.value.js";
 import { InvalidOptionError, MissingOptionValueError, } from "../cliError/cliError.option.js";
-import { isOption, parseBoolean, parseOptionValue, } from "./cliParser.helper.js";
+import { isOption, isOptionValueToken, parseBoolean, parseOptionValue, } from "./cliParser.helper.js";
 /** Parses a long option token from the token stream. */
 export function parseLongOption(tokens, index, definitions, values, allowUnknownOptions) {
     const token = tokens[index];
@@ -50,11 +50,11 @@ export function parseLongOption(tokens, index, definitions, values, allowUnknown
         return index + 1;
     }
     if (value === undefined) {
-        if (tokens[index + 1] === undefined || tokens[index + 1] === "--") {
+        const next = tokens[index + 1];
+        if (!isOptionValueToken(definition, next)) {
             throw new MissingOptionValueError(token);
         }
-        value = tokens[index + 1];
-        assignOptionValue(definition, value, values);
+        assignOptionValue(definition, next, values);
         return index + 2;
     }
     assignOptionValue(definition, value, values);

package/dist/src/cliParser/cliParser.shortOption.js

@@ -5,6 +5,7 @@
  */
 import { CLI_OPTION_PREFIXES } from "../cliConstant/cliConstant.value.js";
 import { InvalidOptionError, MissingOptionValueError, } from "../cliError/cliError.option.js";
+import { isOptionValueToken } from "./cliParser.helper.js";
 import { assignOptionValue } from "./cliParser.longOption.js";
 /** Parses a short option token from the token stream. */
 export function parseShortOption(tokens, index, definitions, values, allowUnknownOptions) {
@@ -44,10 +45,11 @@ export function parseShortOption(tokens, index, definitions, values, allowUnknow
                     assignOptionValue(definition, attachedValue, values);
                     return index + 1;
                 }
-                if (tokens[index + 1] === undefined) {
+                const next = tokens[index + 1];
+                if (!isOptionValueToken(definition, next)) {
                     throw new MissingOptionValueError(`-${short}`);
                 }
-                assignOptionValue(definition, tokens[index + 1], values);
+                assignOptionValue(definition, next, values);
                 return index + 2;
             }
             values[definition.name] = true;
@@ -66,10 +68,11 @@ export function parseShortOption(tokens, index, definitions, values, allowUnknow
         values[definition.name] = true;
         return index + 1;
     }
-    if (tokens[index + 1] === undefined) {
+    const next = tokens[index + 1];
+    if (!isOptionValueToken(definition, next)) {
         throw new MissingOptionValueError(token);
     }
-    assignOptionValue(definition, tokens[index + 1], values);
+    assignOptionValue(definition, next, values);
     return index + 2;
 }
 /** Finds an option by its short flag. */

package/dist/src/cliVersion/cliVersion.update.js

@@ -11,6 +11,7 @@
  *
  * @module cliVersion/update
  */
+import { CLI_ENVIRONMENT } from "../cliConstant/cliConstant.value.js";
 import { compareVersions, isValidVersion } from "./cliVersion.core.js";
 /**
  * Whether the update check is turned off for this environment.
@@ -19,12 +20,13 @@ import { compareVersions, isValidVersion } from "./cliVersion.core.js";
  * mode disable it implicitly.
  */
 export function isUpdateCheckDisabled(env = process.env) {
-    const flag = env["ZUDOJS_NO_UPDATE_CHECK"];
+    const flag = env[CLI_ENVIRONMENT.NO_UPDATE_CHECK];
     if (flag !== undefined && flag !== "" && flag !== "0")
         return true;
-    if (env["CI"] !== undefined && env["CI"] !== "" && env["CI"] !== "false")
+    const ci = env[CLI_ENVIRONMENT.CI];
+    if (ci !== undefined && ci !== "" && ci !== "false")
         return true;
-    if (env["npm_config_offline"] === "true")
+    if (env[CLI_ENVIRONMENT.NPM_OFFLINE] === "true")
         return true;
     return false;
 }

package/dist/src/commands/add.command.js

@@ -88,6 +88,14 @@ export async function runAddCommand(context) {
     }
     context.logger.info(`Adding feature: ${feature}`);
     context.logger.info(`Packages: ${packages.join(", ")}`);
+    // The manifest is read and validated before anything is written: an
+    // unusable manifest used to be discovered after every package.json had
+    // already been rewritten, leaving the project half-updated.
+    const manifest = new ManifestManager(layout.root);
+    const manifestState = await manifest.readResult();
+    if (manifestState.status === "invalid") {
+        throw new CLIGenerationError(`The project manifest at ${manifest.path} is unusable: ${manifestState.reason ?? "unknown reason"}. Fix or delete it, then re-run; nothing has been changed.`);
+    }
     try {
         for (const pkgPath of targets) {
             if (!existsSync(pkgPath)) {
@@ -111,8 +119,15 @@ export async function runAddCommand(context) {
             writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
             context.logger.info(`Updated ${relative(context.cwd, pkgPath) || "package.json"}`);
         }
-        // The manifest records capabilities for the whole project.
-        await new ManifestManager(layout.root).addCapability(feature);
+        // The manifest records capabilities for the whole project. A project
+        // described by a legacy zudojs.config.ts or a package.json block has
+        // none; that is said out loud rather than passed over in silence.
+        if (manifestState.status === "ok") {
+            await manifest.addCapability(feature);
+        }
+        else {
+            context.logger.warn(`No .zudojs/manifest.json in ${layout.root}; "${feature}" was recorded in package.json only.`);
+        }
         if (context.values["skip-install"] !== true) {
             const [file, ...args] = getInstallCommand(layout.packageManager);
             context.logger.info(`Installing dependencies with ${file}...`);

package/dist/src/commands/commandError.helper.d.ts

@@ -0,0 +1,15 @@
+/**
+ * zudojs-cli — Command Error Helpers
+ *
+ * Rendering for errors a command reports to the user.
+ */
+/**
+ * Renders an error together with everything it was caused by.
+ *
+ * Generators wrap failures in a CLIGenerationError whose own message says
+ * only what was being attempted — "Failed to write project files:",
+ * "Failed to generate service: billing" — and the cause carried the reason
+ * (ENOTDIR, EACCES) without anything ever printing it.
+ */
+export declare function describeError(error: unknown): string;
+//# sourceMappingURL=commandError.helper.d.ts.map

package/dist/src/commands/commandError.helper.js

@@ -0,0 +1,28 @@
+/**
+ * zudojs-cli — Command Error Helpers
+ *
+ * Rendering for errors a command reports to the user.
+ */
+/** How many `cause` links are followed before the chain is cut off. */
+const MAX_CAUSE_DEPTH = 5;
+/**
+ * Renders an error together with everything it was caused by.
+ *
+ * Generators wrap failures in a CLIGenerationError whose own message says
+ * only what was being attempted — "Failed to write project files:",
+ * "Failed to generate service: billing" — and the cause carried the reason
+ * (ENOTDIR, EACCES) without anything ever printing it.
+ */
+export function describeError(error) {
+    const parts = [];
+    let current = error;
+    for (let depth = 0; depth < MAX_CAUSE_DEPTH && current instanceof Error; depth += 1) {
+        const message = current.message.replace(/[:\s]+$/, "");
+        if (message.length > 0 && !parts.includes(message)) {
+            parts.push(message);
+        }
+        current = current.cause;
+    }
+    return parts.length > 0 ? parts.join(": ") : String(error);
+}
+//# sourceMappingURL=commandError.helper.js.map