@guanghechen/commander 4.1.0 → 4.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Change Log
 
+## 4.2.0
+
+### Minor Changes
+
+- feat(reporter): add setFlight API for flight tracking feat(commander): unify builtin config for
+  options and commands
+
+### Patch Changes
+
+- Updated dependencies:
+  - @guanghechen/reporter@3.3.0
+
 ## 4.1.0
 
 ### Minor Changes

package/lib/cjs/index.cjs

@@ -24,6 +24,57 @@ function _interopNamespaceDefault(e) {
 var fs__namespace = /*#__PURE__*/_interopNamespaceDefault(fs);
 var path__namespace = /*#__PURE__*/_interopNamespaceDefault(path);
 
+const logLevelOption = {
+    long: 'logLevel',
+    type: 'string',
+    args: 'required',
+    desc: 'Set log level',
+    default: 'info',
+    choices: reporter.LOG_LEVELS,
+    coerce: (raw) => {
+        const level = reporter.resolveLogLevel(raw);
+        if (level === undefined) {
+            throw new Error(`Invalid log level: ${raw}`);
+        }
+        return level;
+    },
+    apply: (value, ctx) => {
+        ctx.reporter.setLevel(value);
+    },
+};
+const logDateOption = {
+    long: 'logDate',
+    type: 'boolean',
+    args: 'none',
+    desc: 'Enable log timestamp',
+    default: true,
+    apply: (value, ctx) => {
+        ctx.reporter.setFlight({ date: Boolean(value) });
+    },
+};
+const logColorfulOption = {
+    long: 'logColorful',
+    type: 'boolean',
+    args: 'none',
+    desc: 'Enable colorful log output',
+    default: true,
+    apply: (value, ctx) => {
+        ctx.reporter.setFlight({ color: Boolean(value) });
+    },
+};
+const silentOption = {
+    long: 'silent',
+    type: 'boolean',
+    args: 'none',
+    desc: 'Suppress non-error output',
+    default: false,
+    apply: (value, ctx) => {
+        if (value) {
+            ctx.reporter.setLevel('error');
+        }
+    },
+};
+
 class CommanderError extends Error {
     kind;
     commandPath;
@@ -139,11 +190,70 @@ const BUILTIN_VERSION_OPTION = {
     args: 'none',
     desc: 'Show version number',
 };
+function normalizeBuiltinConfig(builtin) {
+    const resolved = {
+        option: {
+            logLevel: true,
+            silent: true,
+            logDate: true,
+            logColorful: true,
+        },
+        command: {
+            help: false,
+        },
+    };
+    if (builtin === undefined) {
+        return resolved;
+    }
+    if (builtin === true) {
+        return {
+            option: { logLevel: true, silent: true, logDate: true, logColorful: true },
+            command: { help: true },
+        };
+    }
+    if (builtin === false) {
+        return {
+            option: { logLevel: false, silent: false, logDate: false, logColorful: false },
+            command: { help: false },
+        };
+    }
+    if (builtin.option !== undefined) {
+        if (builtin.option === false) {
+            resolved.option = { logLevel: false, silent: false, logDate: false, logColorful: false };
+        }
+        else if (builtin.option === true) {
+            resolved.option = { logLevel: true, silent: true, logDate: true, logColorful: true };
+        }
+        else {
+            if (builtin.option.logLevel !== undefined)
+                resolved.option.logLevel = builtin.option.logLevel;
+            if (builtin.option.silent !== undefined)
+                resolved.option.silent = builtin.option.silent;
+            if (builtin.option.logDate !== undefined)
+                resolved.option.logDate = builtin.option.logDate;
+            if (builtin.option.logColorful !== undefined) {
+                resolved.option.logColorful = builtin.option.logColorful;
+            }
+        }
+    }
+    if (builtin.command !== undefined) {
+        if (builtin.command === false) {
+            resolved.command = { help: false };
+        }
+        else if (builtin.command === true) {
+            resolved.command = { help: true };
+        }
+        else if (builtin.command.help !== undefined) {
+            resolved.command.help = builtin.command.help;
+        }
+    }
+    return resolved;
+}
 class Command {
     #name;
     #desc;
     #version;
-    #helpSubcommandEnabled;
+    #builtin;
     #reporter;
     #parent;
     #options = [];
@@ -155,7 +265,7 @@ class Command {
         this.#name = config.name ?? '';
         this.#desc = config.desc;
         this.#version = config.version;
-        this.#helpSubcommandEnabled = config.help ?? false;
+        this.#builtin = normalizeBuiltinConfig(config.builtin);
         this.#reporter = config.reporter;
     }
     get name() {
@@ -195,7 +305,7 @@ class Command {
         return this;
     }
     subcommand(name, cmd) {
-        if (this.#helpSubcommandEnabled && name === 'help') {
+        if (this.#builtin.command.help && name === 'help') {
             throw new CommanderError('ConfigurationError', '"help" is a reserved subcommand name when help subcommand is enabled', this.#getCommandPath());
         }
         if (cmd.#parent && cmd.#parent !== this) {
@@ -342,7 +452,7 @@ class Command {
             }
             lines.push('');
         }
-        const showHelpSubcommand = this.#helpSubcommandEnabled && this.#subcommandsList.length > 0;
+        const showHelpSubcommand = this.#builtin.command.help && this.#subcommandsList.length > 0;
         if (this.#subcommandsList.length > 0) {
             lines.push('Commands:');
             const cmdLines = [];
@@ -393,7 +503,7 @@ class Command {
         };
     }
     #processHelpSubcommand(argv) {
-        if (!this.#helpSubcommandEnabled)
+        if (!this.#builtin.command.help)
             return argv;
         if (argv.length < 1 || argv[0] !== 'help')
             return argv;
@@ -722,12 +832,28 @@ class Command {
         const optionMap = new Map();
         const hasUserHelp = this.#options.some(o => o.long === 'help');
         const hasUserVersion = this.#options.some(o => o.long === 'version');
+        const hasUserLogLevel = this.#options.some(o => o.long === 'logLevel');
+        const hasUserSilent = this.#options.some(o => o.long === 'silent');
+        const hasUserLogDate = this.#options.some(o => o.long === 'logDate');
+        const hasUserLogColorful = this.#options.some(o => o.long === 'logColorful');
         if (!hasUserHelp) {
             optionMap.set('help', BUILTIN_HELP_OPTION);
         }
         if (!hasUserVersion && includeVersion) {
             optionMap.set('version', BUILTIN_VERSION_OPTION);
         }
+        if (this.#builtin.option.logLevel && !hasUserLogLevel) {
+            optionMap.set('logLevel', logLevelOption);
+        }
+        if (this.#builtin.option.silent && !hasUserSilent) {
+            optionMap.set('silent', silentOption);
+        }
+        if (this.#builtin.option.logDate && !hasUserLogDate) {
+            optionMap.set('logDate', logDateOption);
+        }
+        if (this.#builtin.option.logColorful && !hasUserLogColorful) {
+            optionMap.set('logColorful', logColorfulOption);
+        }
         for (const opt of this.#options) {
             optionMap.set(opt.long, opt);
         }
@@ -1201,37 +1327,13 @@ class PwshCompletion {
     }
 }
 
-const logLevelOption = {
-    long: 'logLevel',
-    type: 'string',
-    args: 'required',
-    desc: 'Set log level',
-    default: 'info',
-    choices: reporter.LOG_LEVELS,
-    coerce: (raw) => {
-        const level = reporter.resolveLogLevel(raw);
-        if (level === undefined) {
-            throw new Error(`Invalid log level: ${raw}`);
-        }
-        return level;
-    },
-    apply: (value, ctx) => {
-        ctx.reporter.setLevel(value);
-    },
-};
-const silentOption = {
-    long: 'silent',
-    type: 'boolean',
-    args: 'none',
-    desc: 'Suppress non-error output',
-    default: false,
-};
-
 exports.BashCompletion = BashCompletion;
 exports.Command = Command;
 exports.CommanderError = CommanderError;
 exports.CompletionCommand = CompletionCommand;
 exports.FishCompletion = FishCompletion;
 exports.PwshCompletion = PwshCompletion;
+exports.logColorfulOption = logColorfulOption;
+exports.logDateOption = logDateOption;
 exports.logLevelOption = logLevelOption;
 exports.silentOption = silentOption;

package/lib/esm/index.mjs

@@ -1,7 +1,58 @@
-import { Reporter, LOG_LEVELS, resolveLogLevel } from '@guanghechen/reporter';
+import { LOG_LEVELS, resolveLogLevel, Reporter } from '@guanghechen/reporter';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+const logLevelOption = {
+    long: 'logLevel',
+    type: 'string',
+    args: 'required',
+    desc: 'Set log level',
+    default: 'info',
+    choices: LOG_LEVELS,
+    coerce: (raw) => {
+        const level = resolveLogLevel(raw);
+        if (level === undefined) {
+            throw new Error(`Invalid log level: ${raw}`);
+        }
+        return level;
+    },
+    apply: (value, ctx) => {
+        ctx.reporter.setLevel(value);
+    },
+};
+const logDateOption = {
+    long: 'logDate',
+    type: 'boolean',
+    args: 'none',
+    desc: 'Enable log timestamp',
+    default: true,
+    apply: (value, ctx) => {
+        ctx.reporter.setFlight({ date: Boolean(value) });
+    },
+};
+const logColorfulOption = {
+    long: 'logColorful',
+    type: 'boolean',
+    args: 'none',
+    desc: 'Enable colorful log output',
+    default: true,
+    apply: (value, ctx) => {
+        ctx.reporter.setFlight({ color: Boolean(value) });
+    },
+};
+const silentOption = {
+    long: 'silent',
+    type: 'boolean',
+    args: 'none',
+    desc: 'Suppress non-error output',
+    default: false,
+    apply: (value, ctx) => {
+        if (value) {
+            ctx.reporter.setLevel('error');
+        }
+    },
+};
+
 class CommanderError extends Error {
     kind;
     commandPath;
@@ -117,11 +168,70 @@ const BUILTIN_VERSION_OPTION = {
     args: 'none',
     desc: 'Show version number',
 };
+function normalizeBuiltinConfig(builtin) {
+    const resolved = {
+        option: {
+            logLevel: true,
+            silent: true,
+            logDate: true,
+            logColorful: true,
+        },
+        command: {
+            help: false,
+        },
+    };
+    if (builtin === undefined) {
+        return resolved;
+    }
+    if (builtin === true) {
+        return {
+            option: { logLevel: true, silent: true, logDate: true, logColorful: true },
+            command: { help: true },
+        };
+    }
+    if (builtin === false) {
+        return {
+            option: { logLevel: false, silent: false, logDate: false, logColorful: false },
+            command: { help: false },
+        };
+    }
+    if (builtin.option !== undefined) {
+        if (builtin.option === false) {
+            resolved.option = { logLevel: false, silent: false, logDate: false, logColorful: false };
+        }
+        else if (builtin.option === true) {
+            resolved.option = { logLevel: true, silent: true, logDate: true, logColorful: true };
+        }
+        else {
+            if (builtin.option.logLevel !== undefined)
+                resolved.option.logLevel = builtin.option.logLevel;
+            if (builtin.option.silent !== undefined)
+                resolved.option.silent = builtin.option.silent;
+            if (builtin.option.logDate !== undefined)
+                resolved.option.logDate = builtin.option.logDate;
+            if (builtin.option.logColorful !== undefined) {
+                resolved.option.logColorful = builtin.option.logColorful;
+            }
+        }
+    }
+    if (builtin.command !== undefined) {
+        if (builtin.command === false) {
+            resolved.command = { help: false };
+        }
+        else if (builtin.command === true) {
+            resolved.command = { help: true };
+        }
+        else if (builtin.command.help !== undefined) {
+            resolved.command.help = builtin.command.help;
+        }
+    }
+    return resolved;
+}
 class Command {
     #name;
     #desc;
     #version;
-    #helpSubcommandEnabled;
+    #builtin;
     #reporter;
     #parent;
     #options = [];
@@ -133,7 +243,7 @@ class Command {
         this.#name = config.name ?? '';
         this.#desc = config.desc;
         this.#version = config.version;
-        this.#helpSubcommandEnabled = config.help ?? false;
+        this.#builtin = normalizeBuiltinConfig(config.builtin);
         this.#reporter = config.reporter;
     }
     get name() {
@@ -173,7 +283,7 @@ class Command {
         return this;
     }
     subcommand(name, cmd) {
-        if (this.#helpSubcommandEnabled && name === 'help') {
+        if (this.#builtin.command.help && name === 'help') {
             throw new CommanderError('ConfigurationError', '"help" is a reserved subcommand name when help subcommand is enabled', this.#getCommandPath());
         }
         if (cmd.#parent && cmd.#parent !== this) {
@@ -320,7 +430,7 @@ class Command {
             }
             lines.push('');
         }
-        const showHelpSubcommand = this.#helpSubcommandEnabled && this.#subcommandsList.length > 0;
+        const showHelpSubcommand = this.#builtin.command.help && this.#subcommandsList.length > 0;
         if (this.#subcommandsList.length > 0) {
             lines.push('Commands:');
             const cmdLines = [];
@@ -371,7 +481,7 @@ class Command {
         };
     }
     #processHelpSubcommand(argv) {
-        if (!this.#helpSubcommandEnabled)
+        if (!this.#builtin.command.help)
             return argv;
         if (argv.length < 1 || argv[0] !== 'help')
             return argv;
@@ -700,12 +810,28 @@ class Command {
         const optionMap = new Map();
         const hasUserHelp = this.#options.some(o => o.long === 'help');
         const hasUserVersion = this.#options.some(o => o.long === 'version');
+        const hasUserLogLevel = this.#options.some(o => o.long === 'logLevel');
+        const hasUserSilent = this.#options.some(o => o.long === 'silent');
+        const hasUserLogDate = this.#options.some(o => o.long === 'logDate');
+        const hasUserLogColorful = this.#options.some(o => o.long === 'logColorful');
         if (!hasUserHelp) {
             optionMap.set('help', BUILTIN_HELP_OPTION);
         }
         if (!hasUserVersion && includeVersion) {
             optionMap.set('version', BUILTIN_VERSION_OPTION);
         }
+        if (this.#builtin.option.logLevel && !hasUserLogLevel) {
+            optionMap.set('logLevel', logLevelOption);
+        }
+        if (this.#builtin.option.silent && !hasUserSilent) {
+            optionMap.set('silent', silentOption);
+        }
+        if (this.#builtin.option.logDate && !hasUserLogDate) {
+            optionMap.set('logDate', logDateOption);
+        }
+        if (this.#builtin.option.logColorful && !hasUserLogColorful) {
+            optionMap.set('logColorful', logColorfulOption);
+        }
         for (const opt of this.#options) {
             optionMap.set(opt.long, opt);
         }
@@ -1179,30 +1305,4 @@ class PwshCompletion {
     }
 }
 
-const logLevelOption = {
-    long: 'logLevel',
-    type: 'string',
-    args: 'required',
-    desc: 'Set log level',
-    default: 'info',
-    choices: LOG_LEVELS,
-    coerce: (raw) => {
-        const level = resolveLogLevel(raw);
-        if (level === undefined) {
-            throw new Error(`Invalid log level: ${raw}`);
-        }
-        return level;
-    },
-    apply: (value, ctx) => {
-        ctx.reporter.setLevel(value);
-    },
-};
-const silentOption = {
-    long: 'silent',
-    type: 'boolean',
-    args: 'none',
-    desc: 'Suppress non-error output',
-    default: false,
-};
-
-export { BashCompletion, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, logLevelOption, silentOption };
+export { BashCompletion, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, logColorfulOption, logDateOption, logLevelOption, silentOption };

package/lib/types/index.d.ts

@@ -92,6 +92,26 @@ interface ICommandArgumentConfig<T = unknown> {
     /** Custom value transformation (takes precedence over type conversion) */
     coerce?: (rawValue: string) => T;
 }
+interface ICommandBuiltinOptionConfig {
+    /** Enable built-in --log-level option */
+    logLevel?: boolean;
+    /** Enable built-in --silent option */
+    silent?: boolean;
+    /** Enable built-in --log-date/--no-log-date option */
+    logDate?: boolean;
+    /** Enable built-in --log-colorful/--no-log-colorful option */
+    logColorful?: boolean;
+}
+interface ICommandBuiltinCommandConfig {
+    /** Enable built-in help subcommand */
+    help?: boolean;
+}
+interface ICommandBuiltinConfig {
+    /** Built-in options configuration */
+    option?: boolean | ICommandBuiltinOptionConfig;
+    /** Built-in command configuration */
+    command?: boolean | ICommandBuiltinCommandConfig;
+}
 /** Command configuration */
 interface ICommandConfig {
     /** Command name (only for root command) */
@@ -100,8 +120,8 @@ interface ICommandConfig {
     desc: string;
     /** Version (for root --version) */
     version?: string;
-    /** Enable built-in "help" subcommand */
-    help?: boolean;
+    /** Built-in features configuration */
+    builtin?: boolean | ICommandBuiltinConfig;
     /** Default reporter for this command */
     reporter?: IReporter;
 }
@@ -355,6 +375,28 @@ declare class PwshCompletion {
  * ```
  */
 declare const logLevelOption: ICommandOptionConfig<string>;
+/**
+ * Pre-defined --log-date option for controlling timestamp output.
+ *
+ * | Property  | Value     |
+ * | --------- | --------- |
+ * | long      | 'logDate' |
+ * | type      | 'boolean' |
+ * | args      | 'none'    |
+ * | default   | true      |
+ */
+declare const logDateOption: ICommandOptionConfig<boolean>;
+/**
+ * Pre-defined --log-colorful option for controlling colorful output.
+ *
+ * | Property  | Value         |
+ * | --------- | ------------- |
+ * | long      | 'logColorful' |
+ * | type      | 'boolean'     |
+ * | args      | 'none'        |
+ * | default   | true          |
+ */
+declare const logColorfulOption: ICommandOptionConfig<boolean>;
 /**
  * Pre-defined --silent option for suppressing non-error output.
  *
@@ -380,5 +422,5 @@ declare const logLevelOption: ICommandOptionConfig<string>;
  */
 declare const silentOption: ICommandOptionConfig<boolean>;
 
-export { BashCompletion, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, logLevelOption, silentOption };
-export type { ICommand, ICommandAction, ICommandActionParams, ICommandArgumentConfig, ICommandArgumentKind, ICommandArgumentType, ICommandConfig, ICommandContext, ICommandOptionArgs, ICommandOptionConfig, ICommandOptionType, ICommandParseResult, ICommandParsedArgs, ICommandParsedOpts, ICommandResolveResult, ICommandRouteResult, ICommandRunParams, ICommandShiftResult, ICommandToken, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType };
+export { BashCompletion, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, logColorfulOption, logDateOption, logLevelOption, silentOption };
+export type { ICommand, ICommandAction, ICommandActionParams, ICommandArgumentConfig, ICommandArgumentKind, ICommandArgumentType, ICommandBuiltinCommandConfig, ICommandBuiltinConfig, ICommandBuiltinOptionConfig, ICommandConfig, ICommandContext, ICommandOptionArgs, ICommandOptionConfig, ICommandOptionType, ICommandParseResult, ICommandParsedArgs, ICommandParsedOpts, ICommandResolveResult, ICommandRouteResult, ICommandRunParams, ICommandShiftResult, ICommandToken, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanghechen/commander",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "A minimal, type-safe command-line interface builder with fluent API",
   "author": {
     "name": "guanghechen",
@@ -41,7 +41,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@guanghechen/reporter": "^3.2.0"
+    "@guanghechen/reporter": "^3.3.0"
   },
   "scripts": {
     "build": "rollup -c ../../rollup.config.mjs",