goke 6.1.3 → 6.2.0

package/dist/goke.js

@@ -2,7 +2,6 @@
  * Goke — a cac-inspired CLI framework.
  *
  * This file contains the entire core framework:
- * - GokeError: custom error class
  * - Option: CLI option parsing (flags, required/optional values)
  * - Command / GlobalCommand: command definition, help/version output
  * - Goke: main CLI class with parsing, matching, and execution
@@ -13,7 +12,7 @@
 import { EventEmitter } from 'events';
 import pc from 'picocolors';
 import mri from "./mri.js";
-import { coerceBySchema, extractJsonSchema, extractSchemaMetadata, isStandardSchema } from "./coerce.js";
+import { GokeError, coerceBySchema, extractJsonSchema, extractSchemaMetadata, isStandardSchema } from "./coerce.js";
 // ─── Node.js platform constants ───
 const processArgs = process.argv;
 const platformInfo = `${process.platform}-${process.arch} node-${process.version}`;
@@ -70,13 +69,8 @@ const maxVisibleLength = (arr) => {
 };
 const ANSI_RE = /\x1B\[[0-9;]*m/g;
 const visibleLength = (value) => value.replace(ANSI_RE, '').length;
-const commandOrange = (value) => {
-    if (!pc.isColorSupported) {
-        return value;
-    }
-    return `\x1b[38;5;208m${value}\x1b[39m`;
-};
-const optionYellow = (value) => pc.bold(pc.yellowBright(value));
+const commandGreen = (value) => pc.bold(pc.greenBright(value));
+const optionBlue = (value) => pc.bold(pc.blueBright(value));
 const padRight = (str, length) => {
     return visibleLength(str) >= length ? str : `${str}${' '.repeat(length - visibleLength(str))}`;
 };
@@ -176,19 +170,6 @@ const camelcaseOptionName = (name) => {
     })
         .join('.');
 };
-// ─── GokeError ───
-class GokeError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = this.constructor.name;
-        if (typeof Error.captureStackTrace === 'function') {
-            Error.captureStackTrace(this, this.constructor);
-        }
-        else {
-            this.stack = new Error(message).stack;
-        }
-    }
-}
 // ─── Option ───
 class Option {
     rawName;
@@ -205,6 +186,8 @@ class Option {
     default;
     /** Standard JSON Schema V1 schema for type coercion and inference */
     schema;
+    /** Whether this option is deprecated (hidden from help output) */
+    deprecated;
     /**
      * Create an option.
      * @param rawName - The raw option string, e.g. '--port <port>', '-v, --verbose'
@@ -223,6 +206,9 @@ class Option {
             if (meta.default !== undefined) {
                 this.default = meta.default;
             }
+            if (meta.deprecated) {
+                this.deprecated = true;
+            }
         }
         else {
             this.description = '';
@@ -345,7 +331,11 @@ class Command {
             return option.names.includes(name);
         });
     }
-    outputHelp() {
+    /**
+     * Return the formatted help string without printing it.
+     * Useful for embedding help text in documentation, tests, or other programmatic uses.
+     */
+    helpText() {
         const { name, commands } = this.cli;
         const { versionNumber, options: globalOptions, helpCallback, } = this.cli.globalCommand;
         let sections = [
@@ -362,7 +352,8 @@ class Command {
         if (showCommands) {
             const commandRows = commands.map((command) => {
                 const displayName = command.rawName.trim() === '' ? name : command.rawName;
-                const displayOptions = command.isDefaultCommand ? [] : command.options;
+                // Hide deprecated options from subcommand help output
+                const displayOptions = command.isDefaultCommand ? [] : command.options.filter((o) => !o.deprecated);
                 return {
                     command,
                     displayName,
@@ -382,7 +373,7 @@ class Command {
                 body: commandRows
                     .map(({ command, displayName, displayOptions }) => {
                     const commandDescription = formatWrappedDescription(command.description, descriptionWidth, sharedDescriptionColumn);
-                    const commandPrefix = `  ${pc.bold(commandOrange(displayName))}`;
+                    const commandPrefix = `  ${pc.bold(commandGreen(displayName))}`;
                     const commandPadding = ' '.repeat(Math.max(2, sharedDescriptionColumn - (2 + visibleLength(displayName))));
                     const headerLine = commandDescription
                         ? `${commandPrefix}${commandPadding}${commandDescription}`
@@ -393,16 +384,16 @@ class Command {
                     const optionLines = displayOptions
                         .map((option) => {
                         const optionDescription = formatWrappedDescription(optionDescriptionText(option), descriptionWidth, sharedDescriptionColumn);
-                        const optionPrefix = `    ${optionYellow(option.rawName)}`;
+                        const optionPrefix = `    ${optionBlue(option.rawName)}`;
                         const optionPadding = ' '.repeat(Math.max(2, sharedDescriptionColumn - (4 + visibleLength(option.rawName))));
                         return optionDescription
                             ? `${optionPrefix}${optionPadding}${optionDescription}`
                             : optionPrefix;
                     })
                         .join('\n');
-                    return `${headerLine}\n${optionLines}`;
+                    return `${headerLine}\n\n${optionLines}`;
                 })
-                    .join('\n\n'),
+                    .join('\n\n\n'),
             });
         }
         const defaultCommandOptions = this.isGlobalCommand
@@ -432,6 +423,8 @@ class Command {
         if (!this.isGlobalCommand && !this.isDefaultCommand) {
             options = options.filter((option) => option.name !== 'version');
         }
+        // Hide deprecated options from help output
+        options = options.filter((option) => !option.deprecated);
         if (options.length > 0) {
             const longestOptionNameLength = maxVisibleLength(options.map((option) => option.rawName));
             const descriptionColumn = 2 + longestOptionNameLength + 2;
@@ -443,8 +436,8 @@ class Command {
                     const optionLabel = padRight(option.rawName, longestOptionNameLength);
                     const description = formatWrappedDescription(optionDescriptionText(option), descriptionWidth, descriptionColumn);
                     return description
-                        ? `  ${optionYellow(optionLabel)}  ${description}`
-                        : `  ${optionYellow(optionLabel)}`;
+                        ? `  ${optionBlue(optionLabel)}  ${description}`
+                        : `  ${optionBlue(optionLabel)}`;
                 })
                     .join('\n'),
             });
@@ -475,13 +468,16 @@ class Command {
         if (helpCallback) {
             sections = helpCallback(sections) || sections;
         }
-        this.cli.console.log(sections
+        return sections
             .map((section) => {
             return section.title
                 ? `${pc.bold(pc.blue(section.title))}:\n${section.body}`
                 : section.body;
         })
-            .join('\n\n'));
+            .join('\n\n\n');
+    }
+    outputHelp() {
+        this.cli.console.log(this.helpText());
     }
     outputVersion() {
         const { name } = this.cli;
@@ -564,6 +560,24 @@ function createConsole(stdout, stderr) {
         },
     };
 }
+// ─── Error formatting ───
+/**
+ * Format an error for CLI output.
+ * Prints a red "error:" prefix with the message, followed by a dimmed stack trace.
+ */
+function formatCliError(err) {
+    const lines = [];
+    lines.push(`${pc.red(pc.bold('error:'))} ${err.message}`);
+    if (err.stack) {
+        // Extract just the stack frames (skip the first line which is the message)
+        const stackLines = err.stack.split('\n').slice(1);
+        if (stackLines.length > 0) {
+            lines.push('');
+            lines.push(pc.red(pc.dim(stackLines.join('\n'))));
+        }
+    }
+    return lines.join('\n');
+}
 class Goke extends EventEmitter {
     /** The program name to display in help and version message */
     name;
@@ -593,6 +607,8 @@ class Goke extends EventEmitter {
     console;
     /** Terminal width used to wrap help output text */
     columns;
+    /** Exit function called on CLI errors. Defaults to process.exit */
+    exit;
     #defaultArgv;
     /**
      * @param name The program name to display in help and version message
@@ -609,6 +625,7 @@ class Goke extends EventEmitter {
         this.stderr = options?.stderr ?? process.stderr;
         this.console = createConsole(this.stdout, this.stderr);
         this.columns = options?.columns ?? process.stdout.columns ?? Number.POSITIVE_INFINITY;
+        this.exit = options?.exit ?? ((code) => process.exit(code));
         this.#defaultArgv = options?.argv ?? processArgs;
         this.globalCommand = new GlobalCommand(this);
         this.globalCommand.usage('<command> [options]');
@@ -668,19 +685,24 @@ class Goke extends EventEmitter {
         this.globalCommand.example(example);
         return this;
     }
+    /**
+     * Return the formatted help string without printing it.
+     * When a sub-command is matched, returns help for that command.
+     * Otherwise returns the global help.
+     */
+    helpText() {
+        if (this.matchedCommand) {
+            return this.matchedCommand.helpText();
+        }
+        return this.globalCommand.helpText();
+    }
     /**
      * Output the corresponding help message
      * When a sub-command is matched, output the help message for the command
      * Otherwise output the global one.
-     *
      */
     outputHelp() {
-        if (this.matchedCommand) {
-            this.matchedCommand.outputHelp();
-        }
-        else {
-            this.globalCommand.outputHelp();
-        }
+        this.console.log(this.helpText());
     }
     /**
      * Output help for commands matching a prefix.
@@ -726,6 +748,20 @@ class Goke extends EventEmitter {
         this.matchedCommand = undefined;
         this.matchedCommandName = undefined;
     }
+    /**
+     * Handle a CLI error by formatting it and writing to stderr.
+     * For GokeError / coercion errors, also includes a help hint.
+     */
+    handleCliError(err) {
+        this.console.error(formatCliError(err));
+        // Add help hint when help is enabled
+        if (this.showHelpOnExit) {
+            const cmdName = this.matchedCommandName
+                ? `${this.name} ${this.matchedCommandName} --help`
+                : `${this.name} --help`;
+            this.console.error(`\nRun "${cmdName}" for usage information.`);
+        }
+    }
     /**
      * Parse argv
      */
@@ -743,51 +779,60 @@ class Goke extends EventEmitter {
             const bLength = b.name.split(' ').filter(Boolean).length;
             return bLength - aLength;
         });
-        // Search sub-commands
-        for (const command of sortedCommands) {
-            const parsed = this.mri(argv.slice(2), command);
-            const result = command.isMatched(parsed.args);
-            if (result.matched) {
-                shouldParse = false;
-                const matchedCommandName = parsed.args.slice(0, result.consumedArgs).join(' ');
-                const parsedInfo = {
-                    ...parsed,
-                    args: parsed.args.slice(result.consumedArgs),
-                };
-                this.setParsedInfo(parsedInfo, command, matchedCommandName);
-                this.emit(`command:${matchedCommandName}`, command);
-                break; // Stop after first match (greedy matching)
+        // Search sub-commands — mri() can throw coercion errors, catch them
+        try {
+            for (const command of sortedCommands) {
+                const parsed = this.mri(argv.slice(2), command);
+                const result = command.isMatched(parsed.args);
+                if (result.matched) {
+                    shouldParse = false;
+                    const matchedCommandName = parsed.args.slice(0, result.consumedArgs).join(' ');
+                    const parsedInfo = {
+                        ...parsed,
+                        args: parsed.args.slice(result.consumedArgs),
+                    };
+                    this.setParsedInfo(parsedInfo, command, matchedCommandName);
+                    this.emit(`command:${matchedCommandName}`, command);
+                    break; // Stop after first match (greedy matching)
+                }
             }
-        }
-        if (shouldParse) {
-            // Search the default command
-            for (const command of this.commands) {
-                if (command.name === '') {
-                    // Check if any argument is a prefix of an existing command
-                    // If so, don't match the default command (user probably mistyped a subcommand)
-                    const parsed = this.mri(argv.slice(2), command);
-                    const firstArg = parsed.args[0];
-                    if (firstArg) {
-                        const isPrefixOfCommand = this.commands.some((cmd) => {
-                            if (cmd.name === '')
-                                return false;
-                            const cmdParts = cmd.name.split(' ');
-                            return cmdParts[0] === firstArg;
-                        });
-                        if (isPrefixOfCommand) {
-                            // Don't match default command - let it fall through to "unknown command"
-                            continue;
+            if (shouldParse) {
+                // Search the default command
+                for (const command of this.commands) {
+                    if (command.name === '') {
+                        // Check if any argument is a prefix of an existing command
+                        // If so, don't match the default command (user probably mistyped a subcommand)
+                        const parsed = this.mri(argv.slice(2), command);
+                        const firstArg = parsed.args[0];
+                        if (firstArg) {
+                            const isPrefixOfCommand = this.commands.some((cmd) => {
+                                if (cmd.name === '')
+                                    return false;
+                                const cmdParts = cmd.name.split(' ');
+                                return cmdParts[0] === firstArg;
+                            });
+                            if (isPrefixOfCommand) {
+                                // Don't match default command - let it fall through to "unknown command"
+                                continue;
+                            }
                         }
+                        shouldParse = false;
+                        this.setParsedInfo(parsed, command);
+                        this.emit(`command:!`, command);
                     }
-                    shouldParse = false;
-                    this.setParsedInfo(parsed, command);
-                    this.emit(`command:!`, command);
                 }
             }
+            if (shouldParse) {
+                const parsed = this.mri(argv.slice(2));
+                this.setParsedInfo(parsed);
+            }
         }
-        if (shouldParse) {
-            const parsed = this.mri(argv.slice(2));
-            this.setParsedInfo(parsed);
+        catch (err) {
+            if (err instanceof GokeError) {
+                this.handleCliError(err);
+                this.exit(1);
+            }
+            throw err;
         }
         if (this.options.help && this.showHelpOnExit) {
             if (!this.matchedCommand && this.args[0]) {
@@ -959,9 +1004,18 @@ class Goke extends EventEmitter {
         const { args, options, matchedCommand: command } = this;
         if (!command || !command.commandAction)
             return;
-        command.checkUnknownOptions();
-        command.checkOptionValue();
-        command.checkRequiredArgs();
+        try {
+            command.checkUnknownOptions();
+            command.checkOptionValue();
+            command.checkRequiredArgs();
+        }
+        catch (err) {
+            if (err instanceof GokeError) {
+                this.handleCliError(err);
+                this.exit(1);
+            }
+            throw err;
+        }
         const actionArgs = [];
         command.args.forEach((arg, index) => {
             if (arg.variadic) {
@@ -972,7 +1026,20 @@ class Goke extends EventEmitter {
             }
         });
         actionArgs.push(options);
-        return command.commandAction.apply(this, actionArgs);
+        const result = command.commandAction.apply(this, actionArgs);
+        // If the action returns a promise, catch async errors
+        if (result && typeof result === 'object' && typeof result.catch === 'function') {
+            result.catch((err) => {
+                if (err instanceof Error) {
+                    this.handleCliError(err);
+                }
+                else {
+                    this.console.error(`${pc.red(pc.bold('error:'))} ${String(err)}`);
+                }
+                this.exit(1);
+            });
+        }
+        return result;
     }
 }
 export { createConsole, Command };

package/dist/index.d.ts

@@ -11,5 +11,5 @@ export { goke, Goke, Command };
 export { createConsole } from "./goke.js";
 export type { GokeOutputStream, GokeConsole, GokeOptions } from "./goke.js";
 export type { StandardTypedV1, StandardJSONSchemaV1, JsonSchema } from "./coerce.js";
-export { coerceBySchema, extractJsonSchema, wrapJsonSchema, isStandardSchema, extractSchemaMetadata } from "./coerce.js";
+export { GokeError, coerceBySchema, extractJsonSchema, wrapJsonSchema, isStandardSchema, extractSchemaMetadata } from "./coerce.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEnC;;;GAGG;AACH,QAAA,MAAM,IAAI,GAAI,aAAS,EAAE,UAAU,WAAW,SAA4B,CAAA;AAE1E,eAAe,IAAI,CAAA;AACnB,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAA;AAC9B,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACzC,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAC3E,YAAY,EAAE,eAAe,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACpF,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEnC;;;GAGG;AACH,QAAA,MAAM,IAAI,GAAI,aAAS,EAAE,UAAU,WAAW,SAA4B,CAAA;AAE1E,eAAe,IAAI,CAAA;AACnB,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAA;AAC9B,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACzC,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAC3E,YAAY,EAAE,eAAe,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACpF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -8,4 +8,4 @@ const goke = (name = '', options) => new Goke(name, options);
 export default goke;
 export { goke, Goke, Command };
 export { createConsole } from "./goke.js";
-export { coerceBySchema, extractJsonSchema, wrapJsonSchema, isStandardSchema, extractSchemaMetadata } from "./coerce.js";
+export { GokeError, coerceBySchema, extractJsonSchema, wrapJsonSchema, isStandardSchema, extractSchemaMetadata } from "./coerce.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goke",
-  "version": "6.1.3",
+  "version": "6.2.0",
   "type": "module",
   "description": "Simple yet powerful framework for building command-line apps. Inspired by cac.",
   "repository": {