zudojs-cli 2.0.1 → 2.1.1

package/dist/src/bin/bin.runner.js

@@ -0,0 +1,51 @@
+/**
+ * zudojs-cli — Binary Runner
+ *
+ * What the `zudojs` / `zudo` executable does with its arguments: open the
+ * interactive menu for a bare invocation on a terminal, otherwise hand the
+ * arguments straight to the application.
+ */
+import { CLI_ENVIRONMENT, CLI_EXIT_CODES, } from "../cliConstant/cliConstant.value.js";
+/** Whether an environment variable is set to a truthy value. */
+function isTruthy(value) {
+    if (value === undefined)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    return normalized !== "" && normalized !== "0" && normalized !== "false";
+}
+/**
+ * Whether a bare invocation should open the interactive menu.
+ *
+ * Only with no arguments at all, both stdin and stdout attached to a
+ * terminal, and not under CI. Piped, redirected and CI runs keep printing
+ * the help text and exiting 0, so scripts that call `zudojs` are unchanged.
+ */
+export function shouldShowMenu(environment) {
+    return (environment.argv.length === 0 &&
+        environment.stdin.isTTY === true &&
+        environment.stdout.isTTY === true &&
+        !isTruthy(environment.env[CLI_ENVIRONMENT.CI]));
+}
+/**
+ * Runs the binary and resolves with the process exit code.
+ *
+ * @param app - The application with every command registered.
+ * @param environment - The process's arguments, streams and variables.
+ * @param openMenu - Shows the menu; only called when `shouldShowMenu`.
+ */
+export async function runBinary(app, environment, openMenu) {
+    if (!shouldShowMenu(environment)) {
+        return app.run([...environment.argv]);
+    }
+    const outcome = await openMenu();
+    switch (outcome.kind) {
+        case "exit":
+            return CLI_EXIT_CODES.SUCCESS;
+        case "cancel":
+            // Same status as every other aborted prompt (see `cancelled`).
+            return CLI_EXIT_CODES.INTERRUPTED;
+        default:
+            return app.run([...outcome.args]);
+    }
+}
+//# sourceMappingURL=bin.runner.js.map

package/dist/src/bin/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * zudojs-cli — Binary
+ *
+ * The executable's run logic. `zudojs.ts` is the entry script itself and is
+ * deliberately not re-exported: importing it would start the CLI.
+ */
+export { runBinary, shouldShowMenu, type BinaryEnvironment, } from "./bin.runner.js";
+export { isZudojsProject, openMainMenu } from "./bin.menu.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/bin/index.js

@@ -0,0 +1,9 @@
+/**
+ * zudojs-cli — Binary
+ *
+ * The executable's run logic. `zudojs.ts` is the entry script itself and is
+ * deliberately not re-exported: importing it would start the CLI.
+ */
+export { runBinary, shouldShowMenu, } from "./bin.runner.js";
+export { isZudojsProject, openMainMenu } from "./bin.menu.js";
+//# sourceMappingURL=index.js.map

package/dist/src/bin/zudojs.js

@@ -7,7 +7,7 @@
 import { createCLI } from "../cliApplication/index.js";
 import { createCommand } from "../cliCommand/index.js";
 import { CLI_VERSION, FEATURE_NAMES, SCHEMATIC_NAMES, } from "../constants/index.js";
-import { CLI_NAME } from "../cliConstant/cliConstant.value.js";
+import { escapeControlCharacters, resolveInvokedName, } from "../cliApplication/invocation/index.js";
 import { runCreateCommand } from "../commands/create.command.js";
 import { runDevCommand } from "../commands/dev.command.js";
 import { runGenerateCommand } from "../commands/generate.command.js";
@@ -15,9 +15,14 @@ import { runAddCommand } from "../commands/add.command.js";
 import { runBuildCommand } from "../commands/build.command.js";
 import { runDoctorCommand } from "../commands/doctor.command.js";
 import { runInfoCommand } from "../commands/info.command.js";
+import { runBinary } from "./bin.runner.js";
+import { openMainMenu } from "./bin.menu.js";
+// `zudo` and `zudojs` are the same script; help, usage and errors repeat
+// whichever one was typed. Anything else falls back to `zudojs`.
+const invokedName = resolveInvokedName(process.argv[1]);
 const app = createCLI({
     // The name the help output tells people to type, so it must be the binary.
-    name: CLI_NAME,
+    name: invokedName,
     // Read from the CLI's own package.json, so `zudojs --version` cannot
     // drift from the published version.
     version: CLI_VERSION,
@@ -26,6 +31,7 @@ const app = createCLI({
 app.register(createCommand({
     name: "create",
     description: "Create a new Zudojs project",
+    aliases: ["new"],
     arguments: [
         {
             name: "project-name",
@@ -249,14 +255,19 @@ app.register(createCommand({
     },
 }));
 try {
-    const exitCode = await app.run(process.argv.slice(2));
+    const exitCode = await runBinary(app, {
+        argv: process.argv.slice(2),
+        stdin: process.stdin,
+        stdout: process.stdout,
+        env: process.env,
+    }, () => openMainMenu(invokedName, process.cwd()));
     if (exitCode !== 0) {
         process.exit(exitCode);
     }
 }
 catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    console.error(`Error: ${message}`);
+    console.error(`Error: ${escapeControlCharacters(message)}`);
     process.exit(1);
 }
 //# sourceMappingURL=zudojs.js.map

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

@@ -40,8 +40,10 @@ export declare class ZudojsCLI implements CLIApplication {
      * bogus` says so instead of silently printing the global help.
      */
     private resolveHelpTarget;
-    private findCommand;
-    private getCommandArguments;
+    /** Rewrites `zudojs <command>` examples to the name the user typed. */
+    private localize;
+    /** The "did you mean" / "run --help" lines printed under a usage error. */
+    private hintsFor;
     private createContext;
     /** Whether the application is currently running. */
     get isRunning(): boolean;

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

@@ -4,7 +4,7 @@
  * Main CLI application class that orchestrates command registration,
  * parsing, execution, and built-in help/version handling.
  */
-import { CLI_DEFAULTS, CLI_EXIT_CODES, CLI_MESSAGES, CLI_OPTION_PREFIXES, } from "../cliConstant/cliConstant.value.js";
+import { CLI_DEFAULTS, CLI_EXIT_CODES, 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";
@@ -15,6 +15,7 @@ import { createCLIWriter } from "./cliApplication.writer.js";
 import { createCLILogger } from "./cliApplication.logger.js";
 import { isHelpFlag, isHelpRequest, isVersionRequest, printVersion, printHelp, } from "./cliApplication.builtins.js";
 import { printCommandHelp } from "./cliApplication.help.js";
+import { escapeControlCharacters, failureHints, localizeCommandName, locateCommand, requireCommand, } from "./invocation/index.js";
 /* -------------------------------------------------------------------------- */
 /* Application                                                                */
 /* -------------------------------------------------------------------------- */
@@ -40,8 +41,10 @@ export class ZudojsCLI {
         this.description = options.description ?? CLI_DEFAULTS.DESCRIPTION;
         this.cwd = options.cwd ?? process.cwd();
         this.env = options.env ?? process.env;
-        this.logger = options.logger ?? createCLILogger();
         this.commands = new CLICommandRegistry();
+        this.logger =
+            options.logger ??
+                createCLILogger({ transform: (line) => this.localize(line) });
         this.parser = new CLIParser();
         this.writer = createCLIWriter();
         this.hooks = {};
@@ -84,27 +87,26 @@ export class ZudojsCLI {
                 return CLI_EXIT_CODES.SUCCESS;
             }
             if (isVersionRequest(args)) {
+                // `zudojs -v extra` used to print the version and exit 0, silently
+                // discarding the rest of the line.
+                if (args.length > 1) {
+                    throw new InvalidArgumentsError(`Unexpected argument "${args[1]}" after "${args[0]}".`);
+                }
                 printVersion(this.writer, this.version);
                 return CLI_EXIT_CODES.SUCCESS;
             }
-            const command = this.findCommand(args);
-            if (!command) {
-                if (args.length === 0) {
-                    this.printApplicationHelp();
-                    return CLI_EXIT_CODES.SUCCESS;
-                }
-                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);
+            if (args.length === 0) {
+                this.printApplicationHelp();
+                return CLI_EXIT_CODES.SUCCESS;
             }
-            const commandArgs = this.getCommandArguments(args, command);
+            const { index, command } = requireCommand(args, this.commands.list(), this.name);
+            const commandArgs = args.slice(index + 1);
             // Checked before parsing: `--help` is not a declared option, so the
             // parser would reject it as invalid and exit 2.
-            if (commandArgs.some(isHelpFlag)) {
+            // Tokens after `--` are opaque, so `create -- --help` is not a request.
+            const escape = commandArgs.indexOf("--");
+            const flags = escape < 0 ? commandArgs : commandArgs.slice(0, escape);
+            if (flags.some(isHelpFlag)) {
                 printCommandHelp(this.writer, this.name, command);
                 return CLI_EXIT_CODES.SUCCESS;
             }
@@ -125,10 +127,8 @@ export class ZudojsCLI {
                 // error came from argument parsing, re-parsing would fail again.
                 let fallbackContext;
                 try {
-                    const command = this.findCommand(args);
-                    const commandArgs = command
-                        ? this.getCommandArguments(args, command)
-                        : args;
+                    const { index, command } = locateCommand(args, this.commands.list());
+                    const commandArgs = command ? args.slice(index + 1) : args;
                     fallbackContext = this.createContext(commandArgs, command);
                 }
                 catch {
@@ -143,7 +143,13 @@ export class ZudojsCLI {
                 }
                 await this.hooks.onError(normalized, fallbackContext);
             }
-            this.writer.errorLine(normalized.message);
+            const lines = [
+                this.localize(normalized.message),
+                ...this.hintsFor(args, normalized.exitCode),
+            ];
+            for (const line of lines) {
+                this.writer.errorLine(escapeControlCharacters(line));
+            }
             return normalized.exitCode;
         }
         finally {
@@ -171,21 +177,27 @@ export class ZudojsCLI {
             throw new CommandNotFoundError(target);
         return command;
     }
-    findCommand(args) {
-        for (const arg of args) {
-            if (arg.startsWith("-"))
-                continue;
-            const command = resolveCommand(this.commands.list(), arg);
-            if (command)
-                return command;
-        }
-        return undefined;
+    /** Rewrites `zudojs <command>` examples to the name the user typed. */
+    localize(text) {
+        const words = this.commands
+            .list()
+            .flatMap((command) => [command.name, ...(command.aliases ?? [])]);
+        return localizeCommandName(text, this.name, words);
     }
-    getCommandArguments(args, command) {
-        const index = args.findIndex((arg) => arg === command.name || command.aliases?.includes(arg));
-        if (index < 0)
-            return args;
-        return args.slice(index + 1);
+    /** The "did you mean" / "run --help" lines printed under a usage error. */
+    hintsFor(args, exitCode) {
+        const commands = this.commands.list();
+        const helpTarget = isHelpRequest(args) ? args.slice(1) : args;
+        const { index, command } = locateCommand(helpTarget, commands);
+        return failureHints({
+            name: this.name,
+            exitCode,
+            commands,
+            ...(command ? { command } : {}),
+            ...(index >= 0 && !command
+                ? { unknownCommand: helpTarget[index] }
+                : {}),
+        });
     }
     createContext(args, command) {
         const parsed = this.parser.parse(args, command);

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

@@ -20,6 +20,11 @@ export interface CLILoggerOptions {
     /** Line writers, overridable for tests. */
     readonly stdout?: (line: string) => void;
     readonly stderr?: (line: string) => void;
+    /**
+     * Rewrites each rendered line, e.g. to repeat the executable name the
+     * user typed (`zudo create`) in command examples.
+     */
+    readonly transform?: (line: string) => string;
 }
 /** Renders one entry as the single line the user sees. */
 export declare function formatCLILogLine(entry: LoggerEntry): string;

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

@@ -37,20 +37,22 @@ export function createCLILogger(options = {}) {
         (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`));
+    const transform = options.transform ?? ((line) => line);
     return createLogger({
         name: CLI_NAME,
         level: verbose ? LoggerLevel.TRACE : LoggerLevel.INFO,
         // Writes must complete before a command returns; `process.exit` follows
         // an error immediately.
         asynchronous: false,
-        formatter: (entry) => formatCLILogLine(entry),
+        formatter: (entry) => transform(formatCLILogLine(entry)),
         transports: [
             {
                 name: "cli-stdio",
                 enabled: true,
                 write(entry) {
-                    // The formatter's output arrives as the entry message.
-                    const line = entry.message;
+                    // @zudojs/logger carries the formatter's line in `formatted` and
+                    // keeps `message` raw; older releases put the line in `message`.
+                    const line = entry.formatted ?? entry.message;
                     switch (entry.levelName) {
                         case "fatal":
                         case "error":

package/dist/src/cliApplication/invocation/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * zudojs-cli — Invocation
+ *
+ * How the CLI was invoked: the executable name the user typed, where the
+ * command sits in the argument list, and the hints printed under a usage
+ * error.
+ */
+export { CLI_BIN_NAMES, resolveInvokedName, localizeCommandName, } from "./invocation.name.js";
+export { locateCommand, requireCommand, type CommandLocation, } from "./invocation.locate.js";
+export { escapeControlCharacters } from "./invocation.sanitize.js";
+export { suggestCommand, failureHints, type FailureHintInput, } from "./invocation.hint.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/cliApplication/invocation/index.js

@@ -0,0 +1,12 @@
+/**
+ * zudojs-cli — Invocation
+ *
+ * How the CLI was invoked: the executable name the user typed, where the
+ * command sits in the argument list, and the hints printed under a usage
+ * error.
+ */
+export { CLI_BIN_NAMES, resolveInvokedName, localizeCommandName, } from "./invocation.name.js";
+export { locateCommand, requireCommand, } from "./invocation.locate.js";
+export { escapeControlCharacters } from "./invocation.sanitize.js";
+export { suggestCommand, failureHints, } from "./invocation.hint.js";
+//# sourceMappingURL=index.js.map

package/dist/src/cliApplication/invocation/invocation.hint.d.ts

@@ -0,0 +1,30 @@
+/**
+ * zudojs-cli — Failure Hints
+ *
+ * The follow-up lines printed under an error: a "did you mean" for a
+ * mistyped command and a pointer to the right help page.
+ */
+import type { CLICommand } from "../../cliType/cliType.type.js";
+/**
+ * Returns the registered command a mistyped name most likely meant.
+ *
+ * @param input - What the user typed.
+ * @param commands - Registered commands.
+ */
+export declare function suggestCommand(input: string, commands: readonly CLICommand[]): string | undefined;
+/** What a failure hint is built from. */
+export interface FailureHintInput {
+    readonly name: string;
+    readonly exitCode: number;
+    readonly command?: CLICommand;
+    readonly unknownCommand?: string;
+    readonly commands: readonly CLICommand[];
+}
+/**
+ * Returns the hint lines printed after an error message.
+ *
+ * Only usage errors get hints: a failure inside a command already says
+ * what went wrong, and a help pointer would be noise there.
+ */
+export declare function failureHints(input: FailureHintInput): readonly string[];
+//# sourceMappingURL=invocation.hint.d.ts.map

package/dist/src/cliApplication/invocation/invocation.hint.js

@@ -0,0 +1,74 @@
+/**
+ * zudojs-cli — Failure Hints
+ *
+ * The follow-up lines printed under an error: a "did you mean" for a
+ * mistyped command and a pointer to the right help page.
+ */
+import { CLI_EXIT_CODES } from "../../cliConstant/cliConstant.value.js";
+/** The largest edit distance still offered as a suggestion. */
+const MAX_SUGGESTION_DISTANCE = 2;
+/** Levenshtein distance between two short strings. */
+function editDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i += 1) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j += 1) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + cost);
+        }
+        previous = current;
+    }
+    return previous[b.length];
+}
+/**
+ * Returns the registered command a mistyped name most likely meant.
+ *
+ * @param input - What the user typed.
+ * @param commands - Registered commands.
+ */
+export function suggestCommand(input, commands) {
+    const typed = input.trim().toLowerCase();
+    if (typed.length < 2)
+        return undefined;
+    let best;
+    for (const command of commands) {
+        for (const word of [command.name, ...(command.aliases ?? [])]) {
+            // One-letter aliases (`b`, `d`, `g`) are one edit from everything.
+            if (word.length < 2)
+                continue;
+            const distance = word.startsWith(typed) ? 1 : editDistance(typed, word);
+            if (distance > MAX_SUGGESTION_DISTANCE)
+                continue;
+            if (best === undefined || distance < best.distance) {
+                best = { name: word, distance };
+            }
+        }
+    }
+    return best?.name;
+}
+/**
+ * Returns the hint lines printed after an error message.
+ *
+ * Only usage errors get hints: a failure inside a command already says
+ * what went wrong, and a help pointer would be noise there.
+ */
+export function failureHints(input) {
+    if (input.exitCode === CLI_EXIT_CODES.COMMAND_NOT_FOUND) {
+        const suggestion = input.unknownCommand === undefined
+            ? undefined
+            : suggestCommand(input.unknownCommand, input.commands);
+        return [
+            ...(suggestion ? [`Did you mean "${input.name} ${suggestion}"?`] : []),
+            `Run "${input.name} --help" to see all commands.`,
+        ];
+    }
+    if (input.exitCode === CLI_EXIT_CODES.INVALID_ARGUMENTS) {
+        return [
+            input.command
+                ? `Run "${input.name} ${input.command.name} --help" for usage.`
+                : `Run "${input.name} --help" for usage.`,
+        ];
+    }
+    return [];
+}
+//# sourceMappingURL=invocation.hint.js.map

package/dist/src/cliApplication/invocation/invocation.locate.d.ts

@@ -0,0 +1,34 @@
+/**
+ * zudojs-cli — Command Location
+ *
+ * Finds the command token in an argument list and rejects the shapes that
+ * used to be silently misread.
+ */
+import type { CLIArguments, CLICommand } from "../../cliType/cliType.type.js";
+/** Where the command sits in an argument list. */
+export interface CommandLocation {
+    /** Index of the first non-flag token, or -1 when there is none. */
+    readonly index: number;
+    /** The command that token names, when it names one. */
+    readonly command?: CLICommand;
+}
+/**
+ * Locates the command without throwing.
+ *
+ * Only the first non-flag token can be the command. Scanning every token
+ * used to run `zudojs creat dev` as `dev` and `zudojs bogus info` as `info`,
+ * exiting 0 for a command line that contained a typo.
+ */
+export declare function locateCommand(args: CLIArguments, commands: readonly CLICommand[]): CommandLocation;
+/**
+ * Locates the command and throws a usage error when the line is malformed.
+ *
+ * @param name - The invoked executable name, used in the message.
+ * @throws {InvalidArgumentsError} No command, or options before the command.
+ * @throws {CommandNotFoundError} The command token is not registered.
+ */
+export declare function requireCommand(args: CLIArguments, commands: readonly CLICommand[], name: string): {
+    readonly index: number;
+    readonly command: CLICommand;
+};
+//# sourceMappingURL=invocation.locate.d.ts.map

package/dist/src/cliApplication/invocation/invocation.locate.js

@@ -0,0 +1,53 @@
+/**
+ * zudojs-cli — Command Location
+ *
+ * Finds the command token in an argument list and rejects the shapes that
+ * used to be silently misread.
+ */
+import { CLI_MESSAGES, CLI_OPTION_PREFIXES, } from "../../cliConstant/cliConstant.value.js";
+import { CommandNotFoundError } from "../../cliError/cliError.command.js";
+import { InvalidArgumentsError } from "../../cliError/cliError.argument.js";
+import { resolveCommand } from "../../cliParser/cliParser.helper.js";
+/**
+ * Locates the command without throwing.
+ *
+ * Only the first non-flag token can be the command. Scanning every token
+ * used to run `zudojs creat dev` as `dev` and `zudojs bogus info` as `info`,
+ * exiting 0 for a command line that contained a typo.
+ */
+export function locateCommand(args, commands) {
+    const index = args.findIndex((arg) => !arg.startsWith(CLI_OPTION_PREFIXES.SHORT));
+    if (index < 0)
+        return { index };
+    const command = resolveCommand(commands, args[index]);
+    return command ? { index, command } : { index };
+}
+/**
+ * Locates the command and throws a usage error when the line is malformed.
+ *
+ * @param name - The invoked executable name, used in the message.
+ * @throws {InvalidArgumentsError} No command, or options before the command.
+ * @throws {CommandNotFoundError} The command token is not registered.
+ */
+export function requireCommand(args, commands, name) {
+    const location = locateCommand(args, commands);
+    if (location.index < 0) {
+        // Only flags: a lone `-vh` must not be reported as a command named "-vh".
+        throw new InvalidArgumentsError(CLI_MESSAGES.MISSING_COMMAND);
+    }
+    if (location.index > 0) {
+        // `zudojs --verbose info` used to drop `--verbose` without a word, and
+        // `zudojs -p 3000 dev` reported a command named "3000".
+        const leading = args[0];
+        const later = args
+            .slice(location.index)
+            .map((arg) => resolveCommand(commands, arg))
+            .find((command) => command !== undefined);
+        throw new InvalidArgumentsError(`Unexpected option "${leading}" before the command. Options go after the command name: "${name} ${later?.name ?? "<command>"} ${leading}".`);
+    }
+    if (!location.command) {
+        throw new CommandNotFoundError(args[location.index]);
+    }
+    return { index: location.index, command: location.command };
+}
+//# sourceMappingURL=invocation.locate.js.map

package/dist/src/cliApplication/invocation/invocation.name.d.ts

@@ -0,0 +1,37 @@
+/**
+ * zudojs-cli — Invoked Name
+ *
+ * Works out which executable name the user typed (`zudojs` or `zudo`) so
+ * help, usage and error output can repeat it back.
+ */
+/**
+ * Executable names the CLI is installed under.
+ *
+ * `zudojs` is the canonical name; `zudo` is the short alias both the
+ * `zudojs-cli` and `zudojs` packages put on the PATH.
+ */
+export declare const CLI_BIN_NAMES: readonly string[];
+/**
+ * Returns the executable name the CLI was started as.
+ *
+ * Reads the basename of the script path (`process.argv[1]`). Anything that
+ * is not a known executable name — `node dist/src/bin/zudojs.js`, a Windows
+ * npm shim, a bundler's `index.js` — falls back to the canonical `zudojs`.
+ *
+ * @param scriptPath - Usually `process.argv[1]`.
+ * @param known - Accepted executable names.
+ */
+export declare function resolveInvokedName(scriptPath: string | undefined, known?: readonly string[]): string;
+/**
+ * Rewrites command examples in a message to use the name the user typed.
+ *
+ * Only `zudojs` directly followed by a command word is rewritten, so
+ * `zudojs-cli`, `@zudojs/core` and prose such as "the zudojs block in
+ * package.json" are left alone.
+ *
+ * @param text - The message to rewrite.
+ * @param displayName - The invoked executable name.
+ * @param commandWords - Registered command names and aliases.
+ */
+export declare function localizeCommandName(text: string, displayName: string, commandWords: readonly string[]): string;
+//# sourceMappingURL=invocation.name.d.ts.map

package/dist/src/cliApplication/invocation/invocation.name.js

@@ -0,0 +1,69 @@
+/**
+ * zudojs-cli — Invoked Name
+ *
+ * Works out which executable name the user typed (`zudojs` or `zudo`) so
+ * help, usage and error output can repeat it back.
+ */
+import { basename } from "node:path";
+import { CLI_NAME } from "../../cliConstant/cliConstant.value.js";
+/**
+ * Executable names the CLI is installed under.
+ *
+ * `zudojs` is the canonical name; `zudo` is the short alias both the
+ * `zudojs-cli` and `zudojs` packages put on the PATH.
+ */
+export const CLI_BIN_NAMES = Object.freeze([
+    CLI_NAME,
+    "zudo",
+]);
+/** Script extensions stripped before the name is compared. */
+const SCRIPT_EXTENSION = /\.(?:[cm]?[jt]s|cmd|ps1|exe)$/i;
+/** Tokens that may follow the CLI name in a command example. */
+const BUILTIN_WORDS = Object.freeze([
+    "help",
+    "version",
+    "--help",
+    "-h",
+    "--version",
+    "-v",
+    "<command>",
+]);
+/**
+ * Returns the executable name the CLI was started as.
+ *
+ * Reads the basename of the script path (`process.argv[1]`). Anything that
+ * is not a known executable name — `node dist/src/bin/zudojs.js`, a Windows
+ * npm shim, a bundler's `index.js` — falls back to the canonical `zudojs`.
+ *
+ * @param scriptPath - Usually `process.argv[1]`.
+ * @param known - Accepted executable names.
+ */
+export function resolveInvokedName(scriptPath, known = CLI_BIN_NAMES) {
+    if (!scriptPath)
+        return CLI_NAME;
+    const name = basename(scriptPath.replace(/\\/g, "/")).replace(SCRIPT_EXTENSION, "");
+    return known.includes(name) ? name : CLI_NAME;
+}
+/** Escapes a string for literal use inside a regular expression. */
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Rewrites command examples in a message to use the name the user typed.
+ *
+ * Only `zudojs` directly followed by a command word is rewritten, so
+ * `zudojs-cli`, `@zudojs/core` and prose such as "the zudojs block in
+ * package.json" are left alone.
+ *
+ * @param text - The message to rewrite.
+ * @param displayName - The invoked executable name.
+ * @param commandWords - Registered command names and aliases.
+ */
+export function localizeCommandName(text, displayName, commandWords) {
+    if (displayName === CLI_NAME || !text.includes(CLI_NAME))
+        return text;
+    const words = [...commandWords, ...BUILTIN_WORDS].map(escapeRegExp);
+    const pattern = new RegExp(`(?<![\\w@/.-])${CLI_NAME}(?=\\s+(?:${words.join("|")})(?![\\w-]))`, "g");
+    return text.replace(pattern, displayName);
+}
+//# sourceMappingURL=invocation.name.js.map